Ask HN: What's current best practices to document software architecture?

6 points·BrandiATMuhkuh··3 comments

Is UML still the best way to document architecture. Especially for complex web projects (with high parallelism)? Any good tools to suggest?

View on HN

UML has fallen out of favor, in my experience - and for good reason. It's too heavyweight, rigorous, and precise for projects that are rapidly changing. UML documentation often ends up falling behind and becoming useless (or even actively harmful). It also is less effective at conveying many high-level ideas than a short paragraph is.

I've been seeing highly-competent orgs move towards focusing more energy on making code "living documentation" by factoring it in ways that make it easier to understand, and where that is not sufficient, using a lightweight form of high-level documentation such as a wiki. I think this fits better into the lifecycle of most software projects these days.

For API documentation, if necessary (there are people actually integrating with your API), auto-generated documentation is the way to go, IMO. There are a few ways to do this, I can elaborate on a few if you're interested.

I use Markdown Plus. It has a plugin (mermaid) that lets you write some graphs and sequence diagrams in markdown. I find it easier to make updates to diagrams this way. It doesn't make the most beautiful renderings, but works pretty well for me.

Reply on news.ycombinator.com