Documentation style guideline draft. Needs to be discussed! #84
Conversation
|
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. |
JustinCappos
assigned SantiagoTorres, colek42, adityasaky, 06kellyjac and trishankatdatadog
There was a problem hiding this comment.
Thanks Justin
I'd prefer all caps CONTRIBUTING.md but that doesn't particularly matter.
On a slightly related note I tried looking for the code for the in-toto website itself (https://in-toto.io) but I couldn't find it.
There's a link on the website to https://github.com/in-toto/community but unless I'm missing it I don't see anything related to the actual website
| @@ -0,0 +1,65 @@ | |||
| This website is maintained by the in-toto steering committee and is modeled after the [Kubernetes documentation contribution workflow](https://kubernetes.io/docs/contribute/). | |||
There was a problem hiding this comment.
Is this contributing doc ever going to be on a website?
maybe appearing somewhere here? https://in-toto.io/specs/
Or will it always be a contributing guide for this repo?
There was a problem hiding this comment.
I think these guidelines should stay here in the community repo ( https://github.com/in-toto/community/blob/main/CONTRIBUTING.md ). There's a pointer to it from https://github.com/in-toto/docs/blob/master/ROADMAP.md.
The plan is for the content of the Spec to be transformed into a Docs section of the in-toto website. I expect the https://in-toto.io/specs/ repo will continue to be the source for the text, even if that text is broken up into separate files to match separate web pages. We expect to add navigation (site and page TOCs) to make it easier for new users to find introductory information before diving into the demo.
Maybe these guidelines should specify where the doc sources will live, and (when it is decided) what tools are used to produce the public documentation on the in-toto website.
There was a problem hiding this comment.
I think it also depends on the final structure of in-toto repositories. Are we going to rename this one to in-toto/specification and then create a new in-toto/docs repository? Is the specification going to continue to live in the docs repository?
|
|
||
| To get involved with documentation: | ||
|
|
||
| 1. Sign the CNCF [Contributor License Agreement](https://github.com/kubernetes/community/blob/master/CLA.md). |
There was a problem hiding this comment.
I'm not sure the CLA is required/enforced on any in-toto repo right now but I could be wrong
There was a problem hiding this comment.
Yeah, this may be something that needs clarification in project governance?
| 3. Make sure you understand the basic processes for opening a PR. The [Kubernetes documentation on opening a | ||
| pull request](https://kubernetes.io/docs/contribute/new-content/open-a-pr/) is quite detailed and a good place | ||
| to start if you need guidance. |
There was a problem hiding this comment.
This might be a bit confusing as it does talk about the kubernetes docs repo and using hugo which this repo doesn't use.
There was a problem hiding this comment.
The content should probably be copied here and adapted to in-toto
There was a problem hiding this comment.
Agreed, I think this one can only progress once the "architecture" of the docs rendering is decided for in-toto.
|
I think there is still confusion around what goes where in GitHub: The source for the current website (which contains very little of the documentation) is here: -- 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. |
|
|
||
| To get involved with documentation: | ||
|
|
||
| 1. Sign the CNCF [Contributor License Agreement](https://github.com/kubernetes/community/blob/master/CLA.md). |
There was a problem hiding this comment.
Yeah, this may be something that needs clarification in project governance?
| @@ -0,0 +1,65 @@ | |||
| This website is maintained by the in-toto steering committee and is modeled after the [Kubernetes documentation contribution workflow](https://kubernetes.io/docs/contribute/). | |||
There was a problem hiding this comment.
I think it also depends on the final structure of in-toto repositories. Are we going to rename this one to in-toto/specification and then create a new in-toto/docs repository? Is the specification going to continue to live in the docs repository?
| 3. Make sure you understand the basic processes for opening a PR. The [Kubernetes documentation on opening a | ||
| pull request](https://kubernetes.io/docs/contribute/new-content/open-a-pr/) is quite detailed and a good place | ||
| to start if you need guidance. |
There was a problem hiding this comment.
Agreed, I think this one can only progress once the "architecture" of the docs rendering is decided for in-toto.
| As was stated above, for trivial, non-specification changes, create a PR directly. For other changes, you will | ||
| need to discuss this with other folks and create an issue. | ||
|
|
||
| Do not make edits that cause large diffs, which are not relevant to content. For example, do not re-wrap lines |
There was a problem hiding this comment.
One way we've handled this is with pre-commit hooks. Not everyone may install them but, you can also run the pre-commit hooks in a GHA for the PR. There's even some specific linting for markdown documents: https://pre-commit.com/hooks.html
|
|
||
| The American spelling for words is preferred when writing in the English language. | ||
|
|
||
| In general, markdown files are preferred for READMEs and similar documentation. For webpages, when you contribute |
There was a problem hiding this comment.
This also depends on the final repo structure.
| ask on the in-toto documentation slack channel before starting this process. (The main exception to this is | ||
| the [friends](https://github.com/in-toto/friends) repository where adoptions are tracked. Feel free to create | ||
| a PR here directly without talking with us.) There should be an issue created | ||
| on the issue tracker and an ITSC member should thumbs-up this before you begin. If your documentation is for a |
There was a problem hiding this comment.
Definition of ITSC would be valuable here 😄.
|
|
||
| ## Actually Making a Change | ||
|
|
||
| You need to be comfortable with [git](https://git-scm.com/) and [GitHub](https://skills.github.com/) to work effectively in our community. |
There was a problem hiding this comment.
Maybe a link to a good set of resources for learning Git and Github? https://docs.github.com/en/get-started/quickstart/git-and-github-learning-resources - just a thought
There was a problem hiding this comment.
Ah - I see there is the skills.github.com URL as the link for GitHub. If that has tutorials for using Git then perfect 😄 .
|
|
||
| The American spelling for words is preferred when writing in the English language. | ||
|
|
||
| In general, markdown files are preferred for READMEs and similar documentation. For webpages, when you contribute |
There was a problem hiding this comment.
| In general, markdown files are preferred for READMEs and similar documentation. For webpages, when you contribute | |
| In general, markdown files are preferred for READMEs and similar documentation. For webpages, when you contribute |
|
Apart from some minor nits (hopefully they're not too annoying), this looks good to me. |
No description provided.