Ask HN: How do you document engineering efforts?

[chairleader]

Documentation is only good if you can find it again when you need it.

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?

[lgkk]

In the repo, readme. Mostly.

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.

[chairleader]

Thanks for the reply, I'm also a big fan of documentation living inside the repo. I appreciate the framework you describe for the readme as well. Similar to _kb's sibling comment, that sounds like a sane approach to meeting the needs of contributors to and supporters of the codebase.

FWIW, I'm struggling with documentation that support the mix of roles on the team in addition to coders/contributors - QA engineers, product owners, project managers, support teams, etc. A big part is the capture of requirements flowing into proposed solutions and out into support documentation.

In reply to _kb, it did occur to me that there are many job descriptions at play here, and that change is inevitable. Perhaps the answer is simply that it takes many people and several genres of software to keep things from falling through the cracks.

[lgkk]

For sure.

I know JIRA isn't everyone's cup of tea, but it reminded me of Confluence since you mentioned people across domains like that. I only mentioned JIRA because it was connected to Github and other services (sales, marketing, designers, etc.) and that made it easy for people across domains to discuss and have common place for everyone on a project and share information in a meaningful way.

The knowledge lived in one space together, so it was kind of cool that I would pull some data from our data sets to help marketing frame their messaging. Or seeing designers and product managers work together on mocks and share customer insights, and then product engineering teams would build their tickets from it. I could get an insight into what work the technical teams are doing and help them deploy their software.

[_kb]

I really like the system detailed here: https://documentation.divio.com/.

It's targeted more towards externally visible docs, but IMO adapts well for internal resources too.

[chairleader]

Thanks for this link, I agree, that is a fantastic framework for documenting software.

The idea that a reader of a piece of documentation is approaching it with a particular goal is spot on. I suppose I envision either more or perhaps another layer of goals/contexts in addition to what this is outlined here.

A set of use cases I'm thinking of involve the process of changing what a piece of software does. As design documents arise that may or may not apply to a future version of the software, where should that live? Perhaps during the design phase of that release it belongs in one place while designers are iterating on its contents, and later it moves to another place when it is considered a stable reference document?

Plenty of capital P Process behind this question, I suppose. And perhaps there's no getting around some amount of the "librarian" work moving content around to reflect its use.

[_kb]

MADR [1] in its reframed "Any Decision Record" form can be a good tool for that. RFDs [2] also appear to capture a similar intent.

[1]: https://adr.github.io/madr/

[2]: https://rfd.shared.oxide.computer/rfd/0001

[v1l]

I can relate to this a lot.

But I'm trying to understand - why does organizing within folders or tagging with labels not work for you currently?

[chairleader]

The symptoms we experience are: - not capturing key information, often because the challenge of finding a place makes a project out of a task which then gets dropped, - capturing the information in an island somewhere making it unfindable later on, e.g. a loose document in a user's Confluence space.

With a team of folks with different skill levels, when there's information to capture, I'd like there to be a clear single place for it to live so that it's easy to place there and easy to find again.