Developing software with documentation future programmers and collaborators will benefit from

Wed, Jun 8, 2022

See this talked about a lot—given lip service—in terms of the importance of “documentation”, but have best practices in transferability.

• programmers communicating application decisions with future developers CHANGELOG roadmap

From Brian Dominick’s Codewriting:

1. Lots of people in different roles can readily contribute to documentation efforts.
2. Content is managed as discrete components of a whole, instead of merely at the document level.
3. All content can be single-sourced, meaning tech writers and engineers maintain one canonical source of truth, no matter how many places that content needs to appear in the generated docs.

• good example of open source project roadmap ROADMAP.md

• drupal distribution with a docs folder

Over and over again, FarmOS has the best practices.

https://opensource.guide/starting-a-project/

Best practice is to focus on how to get involved from the perspective of a new potential participant.

An example: https://docs.localgovdrupal.org/devs/#get-involved

https://github.blog/2016-08-22-publish-your-project-documentation-with-github-pages/

• why use a docs folder for open source documentation

See https://opensource.com/article/20/8/documentation-open-source-projects for more best practices and