Documentation is only good if you can find it again when you need it.<p>Does anyone have a good pattern for documenting the things the team will need to have to build and deploy working software? I assume for this discussion that we are capturing documentation in a hierarchy such as a wiki or folders of Markdown docs. I'm looking for a pattern that works well for teams both in finding the information and in contributing to the documentation.<p>Key things I find myself needing at key times include these and countless others:
- requirements / constraints behind decisions so that when changes are needed we don't backstep
- runbooks for special cases during deploys
- runbooks for onboarding new teammates
- introductory reading for new teammates<p>My best bet so far has been to try to group things by the context of their use. By this I mean first group by the role one is assuming when they are looking for information, for example "Operations," "Architecture," "Contributing," and group things below that as best I can.<p>I find this has its challenges for teams to get onboard with since it is a bit subjective, and most people don't seem to think about wearing different hats in this way.<p>This also hits a limit when you fold in project planning: documenting things that _may_ come to be part of the software when (and if) work is completed adds a great deal of complexity.<p>What has worked for folks here? Are you using other tools and processes to replace some of these documentation needs?
In the repo, readme. Mostly.<p>Each of my repos have an overview, installation, execution, testing, and deployment sections.<p>I include images or links to Lucid for architecture diagrams.<p>Sometimes I put readme into subdirectories as well if I think it’s warranted. (Rare)<p>I really like markdown. It’s a great format for sharing information for technical folks especially newcomers to the code.<p>As for documenting code itself, I try my best to write simple, clear, self explanatory code with good naming. All of my functions are single responsibility. Everything is clean and organized whether it’s structs or classes.<p>I rarely write comments in code unless it’s for autodoc’ing library code.<p>Not sure if this is what you were asking for - let me know if you mean something else. Interested to know more.
I really like the system detailed here: <a href="https://documentation.divio.com/" rel="nofollow noreferrer">https://documentation.divio.com/</a>.<p>It's targeted more towards externally visible docs, but IMO adapts well for internal resources too.
I can relate to this a lot.<p>But I'm trying to understand - why does organizing within folders or tagging with labels not work for you currently?