Documentation style guideline draft. Needs to be discussed! by JustinCappos · Pull Request #84 · in-toto/specification

JustinCappos · 2023-12-24T23:06:25Z

No description provided.

JustinCappos · 2023-12-24T23:07:35Z

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.

06kellyjac

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

06kellyjac · 2024-01-02T15:44:30Z

@@ -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/).


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?

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.

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?

06kellyjac · 2024-01-02T15:50:25Z

+
+To get involved with documentation:
+
+1.	Sign the CNCF [Contributor License Agreement](https://github.com/kubernetes/community/blob/master/CLA.md).


I'm not sure the CLA is required/enforced on any in-toto repo right now but I could be wrong

Yeah, this may be something that needs clarification in project governance?

06kellyjac · 2024-01-02T15:52:18Z

+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.


This might be a bit confusing as it does talk about the kubernetes docs repo and using hugo which this repo doesn't use.

The content should probably be copied here and adapted to in-toto

Agreed, I think this one can only progress once the "architecture" of the docs rendering is decided for in-toto.

jbogarthyde · 2024-01-02T21:08:12Z

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.

jbogarthyde · 2024-01-05T16:46:52Z

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.

adityasaky

I think this is largely fine minus the specifics of how the docs rendering is expected to happen. I also do prefer "CONTRIBUTING.md" to "Contributing.md".

adityasaky · 2024-01-05T19:21:09Z

+
+To get involved with documentation:
+
+1.	Sign the CNCF [Contributor License Agreement](https://github.com/kubernetes/community/blob/master/CLA.md).


Yeah, this may be something that needs clarification in project governance?

adityasaky · 2024-01-05T19:22:27Z

@@ -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/).


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?

adityasaky · 2024-01-05T19:23:08Z

+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.


Agreed, I think this one can only progress once the "architecture" of the docs rendering is decided for in-toto.

adityasaky · 2024-01-05T19:23:32Z

+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 


do not re-wrap lines

:(

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

adityasaky · 2024-01-05T19:23:56Z

+
+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


This also depends on the final repo structure.

ChaosInTheCRD · 2024-01-08T14:45:03Z

+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


Definition of ITSC would be valuable here 😄.

ChaosInTheCRD · 2024-01-08T14:52:48Z

+
+## 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.


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

Ah - I see there is the skills.github.com URL as the link for GitHub. If that has tutorials for using Git then perfect 😄 .

ChaosInTheCRD · 2024-01-08T14:56:20Z

+
+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


Suggested change

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

ChaosInTheCRD · 2024-01-08T14:57:23Z

Apart from some minor nits (hopefully they're not too annoying), this looks good to me.

Documentation style guideline draft. Needs to be discussed!

2f704c8

JustinCappos marked this pull request as draft December 24, 2023 23:06

JustinCappos assigned SantiagoTorres, colek42, adityasaky, 06kellyjac and trishankatdatadog Dec 24, 2023

06kellyjac reviewed Jan 2, 2024

View reviewed changes

adityasaky reviewed Jan 5, 2024

View reviewed changes

ChaosInTheCRD reviewed Jan 8, 2024

View reviewed changes

		@@ -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/).


		To get involved with documentation:

		1. Sign the CNCF [Contributor License Agreement](https://github.com/kubernetes/community/blob/master/CLA.md).


		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


		## 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.

Conversation

JustinCappos commented Dec 24, 2023

Uh oh!

JustinCappos commented Dec 24, 2023

Uh oh!

06kellyjac left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbogarthyde Jan 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbogarthyde Jan 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbogarthyde commented Jan 2, 2024

Uh oh!

jbogarthyde commented Jan 5, 2024

Uh oh!

adityasaky left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ChaosInTheCRD commented Jan 8, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

jbogarthyde Jan 2, 2024 •

edited

Loading

jbogarthyde Jan 2, 2024 •

edited

Loading