Ask HN: How do you document complex software systems? | Hacker News Reader

Ask HN: How do you document complex software systems?

10 pointsel_benhameen6 comments

We have a codebase that’s fairly well documented. But the infrastructure it’s deployed to and the deployment process itself are not as well documented, and it interacts with other systems in ways that are not well documented or well understood by all of the dev team. Developers who join the project can struggle to understand the full implications of their changes, and developing an understanding of the system as a whole is some combination of reading the code, poking around the infrastructure, finding possibly-outdated documentation that might live in various places, and asking the right people. If someone changes something or someone leaves the team, that makes discoverability even more difficult. So:

1. Where do you document system architecture and the interactions between systems?

2. What does the documentation look like? Diagrams? Text? A combination of the two, or something else entirely?

3. Whose job is it to maintain that documentation?

There's two documents. One is interactions/relationships/interrelations between components (the now).

Second is purpose (the future/past). All architecture evolves to fit the purpose. Some purposes are wrong. Some are outdated. For example, some were built to suit a testing suite or specific library but become unnecessary later. Product decisions go here too.

PNG file to document relationships.

ADR (Architectural Decision Record) and RFCs for purpose, in plaintext. You can put it on a wiki.

Unit tests for components. We don't try to document components. Tests come with problems, but they keep the docs up to date.

We don't maintain the docs. The source of truth is the code (and the tests). We keep records for that reasons - a record doesn't need maintenance. A new decision can link to every other thing that affected the decision.

Many decisions are shaped by edge cases. Tests cover some. Git blame should cover the remainder. I could give a half hour talk on this, but you want to design your workflow so that any line of code can be traced to the decision that caused it.

The C4 model [0] provides a mostly sensible structure and techniques for representing pure software systems across different abstraction levels.

For systems involving software and hardware, or other complex interfacing (both technology and bureaucracy) this starts to delve into the universe of systems engineering. There's a decent assembly of knowledge on that in the SEBoK [1].

As another commenter has already called out too, one of the most valuable sources of information is also _why_ a system is in its current form and _how_ that's changed over time. ADR's [2] really do a good job at nailing this for just about any scale.

[0]: https://c4model.com

[1]: https://sebokwiki.org

[2]: https://adr.github.io

1. Create a repository for architecture documentation and treat it like software that must be maintained and can be defective.

2. The documentation should be written as a technical narrative for people to read like other documentation. This means written first in paragraph form but also contains diagrams of flow control. Be precise and treat this as a product.

3. This must be owned by the stakeholder that owns the corresponding business unit. Surely someone at your company wants to stop failing and stop burning money. If there is not a willpower to succeed then none of this matters. The people to do the work here are senior architects appointed by that owning stakeholder.

1. We started using https://icepanel.io/ for microservices, Software, anything thats documentable for later read.

2. More diagrams, less key strokes

3. We have dedicated page owners on confluence, its mix of engineers, leaders, PM's, QA etc.

I started working on a human readable markup language for non-code dependencies to solve this exact problem.

I wanted something that could be checked in along with the code. Something that would let me do impact analysis and data lineage.

I have only just started to document this idea yesterday.

I write a User's Guide. I try to include everything that a user might need to know. One of my guides is about 40 pages.

I include screenshots to explain stuff, as well as text.

Reply on news.ycombinator.com