This is a classical it depends type of question. Ask different people, get different (and most likely conflicting) answers…

  • As arc42 documentation should always be a combination of text, tables and diagrams, a combination of different tools will often be a better choice than trying to get everything from a single tool (although tool vendors will tell you a different story)
  • Often, (UML) modeling tools come with an abundance of functions and very limited usability. Their learning curve is high and might frustrate many. Overall, team acceptance tends to be low. Despite these usability shortcomings we usually prefer real modeling tools over a pure graphics editor, especially for their better model consistency.
  • Text processors (like Microsoft Word® or Open/Libre-Office) are omnipresent (practically all stakeholders can use them), but developers and other techies often don’t love them. Text processing tools provide limited team- and collaboration features, no real diff/merge, difficult to automate and are difficult to integrate with other tools. Nevertheless arc42 works with this category of tools without hassle.
  • Plaintext-based approaches (like Markdown or AsciiDoc) in combination with graphics-tools (for smaller systems) or modeling tools (for medium to large systems) allow for documentation close-to-source-code and a high degree of automatability - therefore they tend to enjoy high acceptance with development teams.
  • If you strive for documentation-as-code, docToolchain might be your option.
  • We love the combination of wiki plus graphics- or modeling tool. You can generate stakeholder-specific artifacts or pdf from modern wiki systems (like Confluence®).