Request for comment (RFC): grblHAL documentation

[brianredbeard]

In the previous discussion forum I had mentioned that I would draft a proposal and see what folks thought around how to handle documentation (terjeio/grblHAL/discussions/284). I realized that any proposal I made would come with many assumptions which may not be correct for the project. As such I'm breaking this down slightly, separating the idea into:

• motivators (aka the "why" behind the documentation) to keep top of mind when considering the positive/negative aspects of any proposal(s)
• a set of goals I think would be amenable to @terjeio and agreeable to collaborators, but should be discussed and confirmed
• immediate decisions which will be incorporated into

motivators

• remember the purpose of the documentation
  • few folks want to write it
  • everyone needs it at some point
  • without it, users have a hard time getting started
• it should be easy for new/passive contributors to suggest changes
  • the software and processes used to convert source documentation into a consumable asset need to be documented
  • the formatting mechanism used to compose the documentation should not add a significant cognitive burden
    • by far the most common at the moment is "Markdown" and Commonmark has emerged as the most stable specification of markdown
    • a good runner up is reStructuredText which is used by Python itself and (while more complex than markdown) is used by Python and many of it's modules

goals

• generation of documentation needs to be fast
  • the process of rendering the final assets should fail or succeed quickly
    • note: This comes from personal experience with https://github.com/coreos/docs. Due to the large number of pages and the use of Jekyll over time site rendering could take up to five minutes while using Hugo reduced that time back down to seconds. Time spent waiting made developers impatient and as a result they spent less time writing docs to avoid the "pain".
  • changes should occur through pull/merge requests
    • this is easy to do solely through the GitHub GUI, for users unfamiliar/uncomfortable with git
      • GitHub already wrote the documentation (batteries come included): https://docs.github.com/en/github/managing-files-in-a-repository/editing-files-in-another-users-repository
    • pull/merge requests (PRs) should produce a staging version of the documentation for review
      • this would be triggered by a GitHub action
      • this can be challenging with GitHub pages as opposed to other platforms
    • this makes it also easier to execute additional tooling
      • link checking (e.g. looking for 404 errors on the pull requests)
      • spell checking (also possible to do in the source content, but can sometimes introduce other challenges: parsing/ignoring various tags, the way some markup characters are injected e.g. & )
• documentation must be rendered & published as a web page
  • being able to produce the documentation in other forms (e.g. a PDF, ePub file, man pages, etc) is nice to have, not a requirement
    • if producing these forms makes the system too complex for outside contribution, they should be re-considered
• documentation is hosted via some service which is free (as in beer) for free/libre/open source software (aka FLOSS) projects so that grblHAL developers aren't in the business of maintaining servers
  • the reason for doing this work isn't to build a documentation generator, the purpose is to ensure grblHAL has great documentation
  • the systems used to render the documentation should not require more maintenance than the documentation itself
    • this means using an existing system and adding just enough "glue" to make it work. stick to "convention [and documentation] over configuration"
  • the system used to publish and host the documentation should natively support multi-user collaboration
    • contributions to FLOSS development are fundamentally transient. "life happens" and sometimes developers need to take a break (or worse burn out). this can leave gaps in the knowledge around the systems used to manage documentation.
    • the publishing system should make it so that a group of core contributors have multi-user access and should not rely on shared accounts which introduce management and security challenges
• documentation must support versioning
  • many downstream users will "not want to 'touch' [their controllers] once they're working", this is achievable by tagging documentation repositories with the same tags as the code itself
• documentation should live with the code it's documenting
  • when developer working in a repo has to move to a different repository to make a second commit (or set of commits), the documentation is likely to be forgotten (e.g. having a repo for the RP2040 Driver and a second repo for documentation)
  • this moves some of the complexity of generating documentation to the tooling used to compose the documentation (largely the challege of enumerating sources and collocating resources), but also makes it easier to reference components atomically
• documentation should include a clear road-map
  • longer term items should be tracked so that the items in the road-map can be linked to code, allowing users to see the state of a feature rather than having to ask (potentially GitHub projects?)
• documentation should provide clear guidance on setting up a development environment
  • of course users will have opinions and want to tweak things, but many folks will just follow whatever is written down allowing them to get to work on grblHAL rather than focusing on things they don't care about

decisions to be made

• Confirm GPLv3 as the license (this appears to be the license on the majority of the code)
• establish a canonical location for where end users should consume documentation from (e.g. https://docs.grbl.org, https://grbl.org/HAL/docs, etc)
• pick a service for hosting the documentation (e.g. https://readthedocs.org/, https://www.netlify.com/legal/open-source-policy, https://docs.github.com/en/pages)
• set a "kickoff" date after which the initial comment period is closed
• set a goal/deadline for the new documentation being "live"
  • setting a deadline enables community contribution by building trust. when contributors "say what they're going to do" and follow it up with "doing what they said" it establishes a virtuous cycle.

from these decisions the next steps would be:

• sign up for service to host documentation (if needed)
• coordinate any relevant DNS changes
• setup GitHub teams within the organization (these allow users to easily hail relevant parties when help/assistance is needed, as well as being present for role based access control)
  • project administrators (e.g. @grblHAL/admins)
  • documentation administrators (for setting up GitHub Actions, e.g. @grblHAL/docs-admins)
  • documentation reviewers (for approving changes to documentation, e.g. @grblHAL/docs)
• set up appropriate GitHub actions to render documentation for review
• validate published documentation looks correct
• celebrate reaching a milestone 🎉

[brianredbeard]

I'm a very visual person.... I realized that saying "using pull requests for documentation" may be ambiguous to someone who has never used such a workflow. Check out the following two examples:

readthedocs/readthedocs.org#8094
openshift/openshift-docs#31476

In the first, if you scroll to the bottom you'll see a number of useful statuses:

It becomes easy to see who approved changes to the documentation as well as directly getting links to relevant continuous integration (CI) tests executed on the change (I'm not a big fan of CircleCI requiring a login just to look at the status, but that's an implementation detail of choosing to use CircleCI).

After those checks have completed, a staging site is built (using the PR number in the URI to ensure that it's conspicuously not the main documentation): https://docs--8094.org.readthedocs.build/en/8094/

As an alternative implementation of the same idea, look at the OpenShift documentation pull request. In that example the Netlify bot detects the PR, automatically creates a staging site, and adds it as a comment to the pull request. Beyond that a set of CI tests are run using Travis: https://github.com/openshift/openshift-docs/pull/31476/checks?check_run_id=2320364897

[terjeio]

Impressive!

Confirm GPLv3 as the license (this appears to be the license on the majority of the code)

Done.

I'm a very visual person.... I realized that saying "using pull requests for documentation" may be ambiguous to someone who has never used such a workflow.

Does this imply that a new repo for documentation should be added?

[brianredbeard]

It shouldn't be needed (at least for the documentation itself). Effectively what this would look like is a /docs directory in each driver repository to handle documentation specific to the driver. Having a /docs directory in each driver/plugin means the expectation can be set that "a commit for a new feature should include at least basic documentation".

Thus if i created a new feature utilizing Programmable I/O (PIO) on the Raspberry Pi Pico/RP2040 to implement CANBUS support (as an example), my pull-request (PR) should have both the PIO code and the documentation to set it up in /docs.

When the PR is going through continuous-integration (CI) testing, one of the jobs should render a copy of the full documentation as it would be generated from the PR.

As to the "glue" tooling to generate the documentation I think we may be able to get away with that living in grblHAL/core. It's a little bit of mental acrobatics as I think about it because of the dependency ordering. On most other multi-repository projects I've worked on one starts from a checkout of the common repository (i.e. grblHAL/core) and then selects the additional (libraries|plugins|drivers|repositories|etc) which should be pulled in.

At first I thought a separate "docs-tooling" repository would be needed, but as I consider the workflow I realize there isn't really a need and I'm not sure there are enduring benefits to breaking it out as such.

One thing I would suggest though (especially since the drivers rightfully all live in the same GitHub organization) is introducing a meta-data file in repositories under the order which specifies who the maintainer is. There is good prior art on this. Two of my favorites are the MAINTAINERS model used by the Linux kernel and the OWNERS model from Kubernetes.

[brianredbeard]

And as I re-read the "OWNERS" link in the last paragraph I see GitHub has directly added support for a similar mechanism:

https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners

[terjeio]

Sorry for beeing a bit late to respond, we have had a few days of really nice spring weather here that I just had to use for outdoor activities. From snow to 18 C and nearly back in the span of a week...

As to the "glue" tooling to generate the documentation I think we may be able to get away with that living in grblHAL/core. It's a little bit of mental acrobatics as I think about it because of the dependency ordering. On most other multi-repository projects I've worked on one starts from a checkout of the common repository (i.e. grblHAL/core) and then selects the additional (libraries|plugins|drivers|repositories|etc) which should be pulled in.

grblHAL is the other way round, the driver is the one set up to pull the dependencies in. The core and plugins are shared by the drivers. Can't see how this be changed.

As to the "glue" tooling to generate the documentation I think we may be able to get away with that living in grblHAL/core.

I would rather have a separate repository than use the core repo, if anything the core should only be a target for the common documentation, not the tooling itself. A pinned documentation repo should the host tooling and the wiki? Or isn't the wiki needed?

One thing I would suggest though (especially since the drivers rightfully all live in the same GitHub organization) is introducing a meta-data file in repositories under the order which specifies who the maintainer is. There is good prior art on this.

Setting up OWNERS seems to be a good idea - more to learn about. I am coding person and I left it to others to write documentation in my former job, way to go for this project too?