Great topic -- thanks for writing it up. I've been working with open source projects where we committed to the docs-as-code approach. I confess that we did not read all the literature about docs-as-code, but we defined the discipline as including the planning, prioritizing, and tracking of documentation work as well as the writing and publishing activities. This means that any substantive modification to the documentation is initiated with a github issue which is then refined, assigned, and tracked just as the software issues are. Some doc work is included in epics with the associated software modifications. It seems to work quite well.
It means that anyone can file an issue. People who do not want to bother with all the tools can just write the text into the issue or link to an external doc that has the information and then a writer can just pick that up and do the grunt work with authoring tools and PRs -- often even as a good-first-issue. An engineer who is used to git can be assigned an issue to do a first draft, then reassign it to a writer to pick it up and refine it.
We also implemented an "Edit this page" button that a casual reader can use for a small change such as fixing a typo. When this button is clicked, the Markdown source is displayed in the github editor. The user can correct the text then click a couple buttons and the software generates a PR that is then reviewed and approved -- or could be rejected and closed -- through the normal channels.
This is working quite well for now and it seems to me that it will scale as the projects grow larger. I would love to hear your thoughts about this.
Great topic -- thanks for writing it up. I've been working with open source projects where we committed to the docs-as-code approach. I confess that we did not read all the literature about docs-as-code, but we defined the discipline as including the planning, prioritizing, and tracking of documentation work as well as the writing and publishing activities. This means that any substantive modification to the documentation is initiated with a github issue which is then refined, assigned, and tracked just as the software issues are. Some doc work is included in epics with the associated software modifications. It seems to work quite well.
It means that anyone can file an issue. People who do not want to bother with all the tools can just write the text into the issue or link to an external doc that has the information and then a writer can just pick that up and do the grunt work with authoring tools and PRs -- often even as a good-first-issue. An engineer who is used to git can be assigned an issue to do a first draft, then reassign it to a writer to pick it up and refine it.
We also implemented an "Edit this page" button that a casual reader can use for a small change such as fixing a typo. When this button is clicked, the Markdown source is displayed in the github editor. The user can correct the text then click a couple buttons and the software generates a PR that is then reviewed and approved -- or could be rejected and closed -- through the normal channels.
This is working quite well for now and it seems to me that it will scale as the projects grow larger. I would love to hear your thoughts about this.