Ask HN: How do you document engineering efforts?

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.

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.

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.