Ask HN: How do you document engineering efforts?

by chairleader on 11/1/2023, 3:27:25 PM with 8 comments
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?

  • by lgkk on 11/2/2023, 7:33:33 AM

    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.

  • by _kb on 11/2/2023, 9:20:37 AM

    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.

  • by v1l on 11/1/2023, 11:49:36 PM

    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?