<story><title>Ask HN: Is there a better way to document complex software architectures?</title><text>Despite having the &amp;#x27;architect&amp;#x27; title for about five years now, I still sit for hours in Visio &amp;amp; Powerpoint to painstakingly drag boxes and lines around to describe systems.&lt;p&gt;While the system definitions themselves have arguably improved as my skill as an architect has increased, there&amp;#x27;s been no such improvement in the speed or method I use to describe them. My visuals are perfunctory, powerpoint-fu is lacking, and the end result always has plenty of room for improvement. It then gets saved as PDF and shelved as an artefact that is disconnected from all the other architectures, and the system boundaries are inevitably out of date by the time the next person looks at it.&lt;p&gt;So much craft has been put into better languages, better compilers, and better IDEs for the software developer, I&amp;#x27;m absolutely confused - where is the modern &amp;#x27;IDE&amp;#x27; for the Software Architect?</text></story><parent_chain><item><author>Msurrow</author><text>Well, you need to use an architecture modelling tool to work [efficiently] with architecture models.&lt;p&gt;Here are some I know of:&lt;p&gt;Sparx’s Enterprice Architect&lt;p&gt;NoMagic’s MagicDraw&lt;p&gt;Qualiware&lt;p&gt;Achimate (the tool, not the standard)&lt;p&gt;There are surely more out there. I know both Sparx and MagicDraw have the possibility to write your own custom plugins for the tool. If you are in a big enough shop that will become very handy at some point. Qualiware have better publication options than the others, as far as I know, but not completely sure. The Archimate tool probably only supports the Archimate notation standard, where as the others support BPMN, UML, DMN etc. So I’d go for those, unless you are really heavy into TOGAF, then Archimate may make sense.&lt;p&gt;Edit: these are “big” tools that can do alot of differnet stuff and you wont ever need all of the features in one of them. But also means you need to dedicate some time to learn how to use it (alot more time than you needed to learn PP or Visio)</text></item></parent_chain><comment><author>sytse</author><text>If you want to keep everything up to date I recommend checking your diagrams in with your code. GitLab has support for plantUML &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;docs.gitlab.com&amp;#x2F;ee&amp;#x2F;administration&amp;#x2F;integration&amp;#x2F;plantuml.html&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;docs.gitlab.com&amp;#x2F;ee&amp;#x2F;administration&amp;#x2F;integration&amp;#x2F;plantu...&lt;/a&gt; and Mermaid &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;docs.gitlab.com&amp;#x2F;ee&amp;#x2F;user&amp;#x2F;markdown.html#mermaid&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;docs.gitlab.com&amp;#x2F;ee&amp;#x2F;user&amp;#x2F;markdown.html#mermaid&lt;/a&gt;</text></comment>
<story><title>Ask HN: Is there a better way to document complex software architectures?</title><text>Despite having the &amp;#x27;architect&amp;#x27; title for about five years now, I still sit for hours in Visio &amp;amp; Powerpoint to painstakingly drag boxes and lines around to describe systems.&lt;p&gt;While the system definitions themselves have arguably improved as my skill as an architect has increased, there&amp;#x27;s been no such improvement in the speed or method I use to describe them. My visuals are perfunctory, powerpoint-fu is lacking, and the end result always has plenty of room for improvement. It then gets saved as PDF and shelved as an artefact that is disconnected from all the other architectures, and the system boundaries are inevitably out of date by the time the next person looks at it.&lt;p&gt;So much craft has been put into better languages, better compilers, and better IDEs for the software developer, I&amp;#x27;m absolutely confused - where is the modern &amp;#x27;IDE&amp;#x27; for the Software Architect?</text></story><parent_chain><item><author>Msurrow</author><text>Well, you need to use an architecture modelling tool to work [efficiently] with architecture models.&lt;p&gt;Here are some I know of:&lt;p&gt;Sparx’s Enterprice Architect&lt;p&gt;NoMagic’s MagicDraw&lt;p&gt;Qualiware&lt;p&gt;Achimate (the tool, not the standard)&lt;p&gt;There are surely more out there. I know both Sparx and MagicDraw have the possibility to write your own custom plugins for the tool. If you are in a big enough shop that will become very handy at some point. Qualiware have better publication options than the others, as far as I know, but not completely sure. The Archimate tool probably only supports the Archimate notation standard, where as the others support BPMN, UML, DMN etc. So I’d go for those, unless you are really heavy into TOGAF, then Archimate may make sense.&lt;p&gt;Edit: these are “big” tools that can do alot of differnet stuff and you wont ever need all of the features in one of them. But also means you need to dedicate some time to learn how to use it (alot more time than you needed to learn PP or Visio)</text></item></parent_chain><comment><author>donjoe</author><text>To add to this: I highly recommend reading into INCOSE&amp;#x27;s standards and recommendations on SysML.&lt;p&gt;Start by going through one of their last talks:
&lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;sdincose.org&amp;#x2F;rsvpmaker&amp;#x2F;state-of-sysml-2018-09-12&amp;#x2F;&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;sdincose.org&amp;#x2F;rsvpmaker&amp;#x2F;state-of-sysml-2018-09-12&amp;#x2F;&lt;/a&gt;</text></comment>