
Ask HN: What's current best practices to document software architecture? - BrandiATMuhkuh
Is UML still the best way to document architecture. Especially for complex web projects (with high parallelism)? 
Any good tools to suggest?
======
iEchoic
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.

------
mrits
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.

------
ParameterOne
.

