Documents people actually read

I am a Senior Architect for a Defense contractor

My main role in our Enterprise Architecture team is to be the local expert for Sparx EA. This is probably because I’ve been using it for the longest time. I really like introducing new architects to EA, because it takes all the theoretical learning they have got from the doing our in-house Archimate training, and makes a lot more real. They can also see how to approach the same business problem from lots of different ways. I even don’t mind helping them to get used to EA’s strange little ways of doing things – all tools of any complicity have these. What I really thing is a waste of my time is (or rather ‘was’) endlessly generating and polishing the documents we need to produce.

As a team of Enterprise Architects, we want to add as much value to the business as possible. The consumers of our documents – probably our most important stakeholders – are busy people, with lots of technical & business knowledge, and we really need to them to validate the knowledge they have given us.

We have a mandatory set of documents which we need to give create. Some are legally required, others are company standards. These document has tightly defined sections, which have to contain defined sets of information. But within that we have some scope to change the way things are presented. This is where we had problems with the built-in EA documents generators.

I have been an EA users for nearly 10 years, and during that time I have created 100s of documents using those EA built-in generators, so they definitely work. But getting them to create exactly the right content in exactly the right style, and making everything work with our defined standards was always hard. And Sparx do seem  keep changing how this all works. It was around 2020, during the COVID-19 lockdown, that I discovered eaDocX. I tried to make a ‘Quick Document’ from the requirements of one project, and immediately got a document. That’s the hard part of the Sparx approach – you can do 90% of the work, and still get no document at all. More important, it looked fine, not at all like a generated document.  It still needed refining, but this was refining not just how this document would look, but all the other requirements documents for all other projects. It had a ToC, cover page, ToF and even (eventually) a glossary. This was a step change in our document quality and readability.

I think it took a few hours to make my first document look exactly how I wanted it, and I used the hyperlinks a lot. This made the document a bit ‘busy’ to look at, but the information was already there, and once I explained it to the first set of readers, they saw the benefit.

Repository structure

We have now been eaDocX users for about 4 years. I find that I don’t spend as much time as before in teaching new architects how to create documents: we have a family of all the most-used document types, and they need a one-off document, they can usually work out how to make from one of the others.

One thing I was not expecting was that we now have more flexibility on how we structure the model.

eaDocX doesn’t seem to mind if we move whole packages from one place to another, so we can structure the EA repository the way that makes sense to the architects. We have done 2 serious reorganizations of the repository in the last 4 years, and in both cases, we only made minor changes to the documents.