Literature notes based on highlights in [[Docs Like Code]]. In [[Technical Writing]], documentation is most effective when it is treated like code. ## How docs can be treated like code ### Development [[Agile]] and other methodologies used to plan and build code are also useful for planning and building documentation: - Working in [[Sprint]] - The preference for building small, bite-sized chunks that have production impact Docs have a front-end too. Docs should be beautifully and intuitively presented. - The Read the Docs theme is "the gold standard". This theme is called "Sphinx" and is open-sourced. Read the Docs also hosts docs. ### Storage and versioning Code is usually stored in version-controlled repositories. Documentation can be kept in the same repository (on GitHub, for example). Storing and versioning them together: - reinforces that documentation as a necessary part of a release - reduces friction on the part of developers who may not otherwise contribute to documentateion - ties release cycles together, so that the docs have the same version as the code and are always in sync - makes it easier to roll back changes when code has to be rolled back, too. - keeps [[Context-switching]] to a minimum for both developers and writers - enables asynchronous work on issues without conflicts #### Structure of docs and code in the same repository - Centralized: Docs changes are pushed to the main branch. - Feature branch: Docs are treated like features that are worked on in a separate branch, then merged back. - Advantage: the main branch never has broken code, so CI processes can be used to publish its contents automatically. - Gitflow: Docs are pushed to feature branches, and then the team has rules for how and when those branches are merged. - Forking: Docs are worked on as a fork of the main branch, and then a merge to the main branch is requested regularly. #### Reasons _not_ to store docs along with code - You think documentation might have a different version from code, such as if they're not on the same release cycle. - The documentation is multilingual, in which case it may be important to "freeze" code so that translators can work on that frozen copy and know how far behind they are. - Complexity ### CI/CD The same CI/CD tools that build code can be used to build documentation, so that they are published automatically. The lack of manual intervention encourages others to contribute to docs. Webhooks used to integrate GitHub with other team tools like Slack and email can be used for docs as well, informing the team about documentation releases and changes as well. ### Review and Collaboration Most development teams already have a thorough process of reviewing code before releasing it; documentation also benefits from being coupled to this process. - Defects should be logged against documentation, and when one is fixed, the commit message should reference that bug to aid the reviewer. ## Related - [[Technical Writing]] and [[Writing]] - [[Version Control System]] - [[GitHub]] - [[Modern Technical Writing]] - [[sources/Presentation/Mine/Load tests as code - An intro to k6]] - [[Test as code|Tests as code]] - [[Coding and writing are converging]] ## For referencing elsewhere ``` Gentle, A. (2018). _Docs like code_. Lulu.com. [[Docs Like Code|Highlights]] and [[Docs Like Code (lit)|literature notes]]. ```