Consider storing documentation in _the same_ repository as code. ## How to store content alongside code ### Make it easy for others to contribute While there should still be a separation between documentation and application code, keeping them in the same repository further encourages developers to contribute (after all, they're already pulling and pushing to the same repository). Get help where you can by setting up a framework that facilitates contributions. ### Version-control documentation Using Git means you can take advantage of Git's version control, but also its pull request features that encourage others (especially developers) to contribute documentation while giving you some control over what's added. Adding a good `README.md` that describes how to contribute takes it a step further by making it clear you welcome contributions. Being able to roll back changes in documentation when corresponding code changes are rolled back is easier than manually having to synchronize them. ### Synchronize documentation and code releases Using the same repo also ensures that documentation and code versions are in sync. ### Educate others that documentation is part of code Create a culture where code isn't released without corresponding documentation. Having both in the same repository reinforces and formalizes that concept. ### Reduce rework and [[Context-switching]] If the workflows for writing code and writing documentation are similar, then there is less need for context-switching on the part of developers and writers. ### Keep a changelog People want to see what's changing, and the frequency of these updates gives them confidence that the product is being actively maintained. ## Reasons _not_ to store docs alongside 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 ## Related - [[Technical Writing]] - Gentle, A. (2018). _Docs like code_. Lulu.com. [[Docs Like Code|Highlights]] and [[Docs Like Code (lit)|literature notes]].