Hacker News Reader

Comment by jlcases | Hacker News Reader

What impresses me most about technical documentation like this is how it structures knowledge into comprehensible layers. This article manages to explain an extremely complex system by establishing clear relationships between components.

I've been experimenting with similar approaches for documentation in open source projects, using knowledge graphs to link concepts and architectural decisions. The biggest challenge is always keeping documentation synchronized with evolving code.

Has anyone found effective tools for maintaining this synchronization between documented architecture and implemented code? Large projects like Darwin must have established processes for this.

View on HN

> Has anyone found effective tools for maintaining this synchronization between documented architecture and implemented code?

Yes, it's called structure, discipline, and iterative improvement.

Keep the documentation alongside the code. Think in BSD terms: the OS is delivered as a whole; if I modify /bin/ls to support a new flag, then I update the ls.1 man page accordingly, preferably in the same commit/PR.

The man pages are a good reference if you already have familiarity with the employed concepts, so it's good to have an intro/overview document that walks you through those basics. This core design rarely sees radical changes, it tends to evolve - so adapt the overview as you make strategic decisions. The best benchmark is always a new hire. Find out what is it that they didn't understand, and task them with improving the document.

> Has anyone found effective tools for...

Managing management?

Code comments and documentation make no money, only features make money.

Bitter experience...

Try working as a manager.

Software development is just one piece of the bigger picture that your manager is concerned with, same way as adding features is just one among your many responsibilities.

Managers understand risk. Communicate the risk of disregarding bugfixes, documentation, technical debt, even if it takes a lot of handholding. Expect no less from your manger: if they can communicate client expectations, budget constraints, and most importantly: long-term strategy, together you may be able to devise a better plan to address your own concerns.

In other words, empathy can go both ways.

And yeah, there are bad managers, just like there are bad coders. Sometimes it's an interpersonal problem. It's called life.

i suggest you have a look at https://podlite.org/ which encourages you to interweave docs with source code

Reply on news.ycombinator.com