Hacker News Reader

Comment by Ididntdothis | Hacker News Reader

Don’t do it like me and overthink it. Just write down all your thoughts informally. Make diagrams by hand. Only once you have most content then think about formatting and structure. A lot of people produce nicely looking docs without much content. I much prefer a bunch of simple notes that describe the thought process

View on HN

I agree. I used to work on a project where everyone involved in the initial design had left the company, and documentation was spotty. The major issues I had working with the code were all related to not understanding the underlying design choices, e.g. why a certain model was chosen over another or how a certain abstraction was intended to be extended with new functionality.

Stuff that can be formalized in a systematic manner is usually stuff you can figure out on your own in a text editor or IDE.

We've been capturing those decisions in ADRs (https://www.thoughtworks.com/radar/techniques/lightweight-ar...) for the past year or so, and they've been incredibly helpful even for those involved in the original decisions that want to revisit the rationale - I can only imagine how helpful they'd be in a situation like yours.

So much this. Working for Enterprise I saw so many 20 page architectural documents that were borderline impossible to parse and were about as illuminating as a 30 second conversation.

But then it is all .. vague. I do hope something better than can be done.. hand drawn diagrams can't represent details at different levels of magnitude, like for example why statecharts are very expressive compared to other diagrams is it's ability to have arbitrary levels of nesting, which is not possible with handdrawn or even printed diagrams.

I feel like resorting to simple hand drawn diagrams, is in a way declaring failure on being able to describe complex software requirements and structure/ behavior in a systematic graphical manner.

Just make sure your stuff really expresses something and isn’t just pretty as I see quite a bit.

The details will always have to be looked at by the inheritors - it's more important to not say something wrong or contradictory IMO. When I've had to do something like this in the past I circle through it, documenting the high-level ops before details anywhere. Tricky or especially complicated details next, then the operational details for as much as I've time for.

I'm doing this now for a couple of things I've inherited because my predecessors either never documented it or it's been lost to time. High-level flow, tricky and/or problematic bits with operational & recovery info, then the mundane as I have time. That means the mundane or some of the less-tricky tricky bits will be "vague" for a while.

What works for me is to do things by hand, until all the possible information I might want to share is present. I call it my inventory.

Then work on refining, editing, deleting, modifying.

Separate the creation from the editing/communication.

This x1000

You're absolutely right about not overthinking. Any architecture doc is better than none. Even if the thinking it describes is incoherent or if it describes coherent thinking sloppily. And even during editing, there's only one thing I want my principal engineer to keep in mind. Inside the technical vision, tell me a little about implementation details. Either pulled in from below or, if the principal is risen from my ranks, written from experience.

Reply on news.ycombinator.com