in-toto
Documentation style guideline draft. Needs to be discussed!
This PR needs to be discussed by the in-toto community and folks from the documentation group in the CNCF. I'd love for us to decide on this at a future community meeting.
I think there is still confusion around what goes where in GitHub: https://github.com/in-toto/docs -- the spec itself is there, along with a script that generates the PDF https://github.com/in-toto/in-toto/tree/develop/doc -- the sources(?) and makefile for the generated doc for the Python Reference Implementation)
The source for the current website (which contains very little of the documentation) is here: https://github.com/in-toto/in-toto.io/tree/master/content (this is not obvious, better naming could help)
-- CNCF recommends a single source for the website, so the source files for all new web doc pages should probably be here. That would include the actual text (currently mostly what's in the spec), and also whatever templates and makefiles are needed to generate the pages. What those source files look like and how they are organized depends on what tool we end up using to produce the doc pages.
I would suggest deciding on the tool(s) to be used to produce the web-based doc (perhaps Read the Docs which is currently in use for the Python reference doc) -- and specify that workflow as part of the contribution guidelines.
Apart from some minor nits (hopefully they're not too annoying), this looks good to me.
