Don't know where to start? Watch our free starter videos and save lots of time and consultant fees

Articles Questions

July 26, 2020

Should You Automate Your Software Architecture Documentation?

Dr. Oliver Eidel

Question

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?

Short Answer

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.

On a slighty different note: You want to get your medical software certified under MDR but don't know where to start? No worries! That's why we built the Wizard. It's a self-guided video course which helps you create your documentation yourself. No prior knowledge required. You should check it out.

Or, if you're looking for the most awesome (in our opinion) eQMS software to manage your documentation, look no further. We've built Formwork, and it even has a free version!

If you're looking for human help, did you know that we also provide some limited consulting? It's limited because we are not many people. We guide startups from start to finish in their medical device compliance.

Congratulations! You read this far.

Get notified when we post something new.

Sign up for our free newsletter.

Dr. Oliver Eidel

I'm a medical doctor, software engineer and regulatory dude. I'm also the founder of OpenRegulatory.

Through OpenRegulatory, I've helped 100+ companies with their medical device compliance. While it's also my job that we stay profitable, I try to dedicate a lot of my time towards writing free content like our articles and templates. Maybe that will make consulting unnecessary some day? :)

If you're still lost and have further questions, reach out any time!

Comments

If you have any questions or would like to share your opinion publicly, feel free to comment below. If you'd like to reach out privately, send us a message.

No QMS on this planet will save you from creating crappy software.