The days of monolithic, 100-page architecture documents are over. Agile teams move too fast for static documentation to remain accurate. If documentation isn't treated as code, it becomes legacy debt the moment it's published.
The single most important rule: Documentation should live in the same repository as the code it describes. When developers update an API route, they should update the Mermaid sequence diagram in the same Pull Request. If the diagram is locked away in a corporate Wiki, it will never be updated.
Don't try to cram every detail into a single diagram. Use the C4 model for visualizing software architecture:
Mermaid flowcharts are perfect for creating Context and Container diagrams quickly.
If you can generate architecture diagrams from your source code automatically, do it. But for conceptual diagrams that describe intent rather than current state, Diagram-as-Code tools are essential.