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.
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
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.
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.
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.
What has worked for folks here? Are you using other tools and processes to replace some of these documentation needs?
Each of my repos have an overview, installation, execution, testing, and deployment sections.
I include images or links to Lucid for architecture diagrams.
Sometimes I put readme into subdirectories as well if I think it’s warranted. (Rare)
I really like markdown. It’s a great format for sharing information for technical folks especially newcomers to the code.
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.
I rarely write comments in code unless it’s for autodoc’ing library code.
Not sure if this is what you were asking for - let me know if you mean something else. Interested to know more.
It's targeted more towards externally visible docs, but IMO adapts well for internal resources too.
But I'm trying to understand - why does organizing within folders or tagging with labels not work for you currently?