TE
TechEcho
Home24h TopNewestBestAskShowJobs
GitHubTwitter
Home

TechEcho

A tech news platform built with Next.js, providing global tech news and discussions.

GitHubTwitter

Home

HomeNewestBestAskShowJobs

Resources

HackerNews APIOriginal HackerNewsNext.js

© 2025 TechEcho. All rights reserved.

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

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

3 comments

iEchoicabout 8 years ago
UML has fallen out of favor, in my experience - and for good reason. It&#x27;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.<p>I&#x27;ve been seeing highly-competent orgs move towards focusing more energy on making code &quot;living documentation&quot; 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.<p>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&#x27;re interested.
mritsabout 8 years ago
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&#x27;t make the most beautiful renderings, but works pretty well for me.
ParameterOneabout 8 years ago
.