Technical Documentation 1 answer

Should You Automate Your Software Architecture Documentation?

Anonymous · Updated May 08, 2024
For our software architecture documentation, we’re planning to have some high-level system diagrams. Drawing these manually seems inefficient, and we fear that they’ll be outdated soon when we continue writing code and forget to update them.

We’re considering automating this process by using tools which read your code and auto-generate software architecture diagrams based on it. What do you think?

Join the discussion. Leave a comment. Guest comments are welcome — add your email to get reply notifications.

No comments yet. Be the first to share your thoughts.

Discussion

1 Answer

Accepted answer Dr. Oliver Eidel · Founder & CEO, OpenRegulatory ·
No. Do it manually.

Long Answer

Your software architecture diagram should be on a rather high level (see the example here). It’ll be really hard to automate this with code because it’ll span across multiple git repositories and programming languages.

Also, the idea is to think about the architecture first before implementing it, and auto-generating it from your code assumes that you’ll write the code first. That doesn’t make a lot of sense.

Software Architecture vs. Interface Documentation

The story’s a bit different when it comes to interface documentation. An interface could be a REST API or the class / instance methods in object-oriented programming languages. There’s no value in having a human go through your code and write those down! And there are tools for that which do a great job.

As all regulatory requirements, try to approach this from an angle of “What could be useful for us?”:

Quickly drawing up some system diagrams before diving into code? Sounds like a good idea!

Documenting APIs so that new developers can be on-boarded faster? Also doesn’t sound too bad.

Try to avoid creating regulatory documentation only for compliance’s sake. It should be useful for you.

Join the discussion. Leave a comment. Guest comments are welcome — add your email to get reply notifications.

No comments yet. Be the first to share your thoughts.

Want to add your answer to this question?
Write an answer under your name by logging in or signing up, or post anonymously.

Still have a question? Ask a question here publicly — for free.

Or talk to one of our consultants — first calls are free. Check out our services and prices.

Looking to automate your regulatory work? Check out our eQMS, Formwork. Built for lean, founder-led companies. There’s a free version too.