7 Steps to Agile Documents


“How documents can HELP your project, not stop it “

If you are an author of documents – especially technical documents – you’ll know how frustrating it is when, after days or weeks of effort, and when you finally send out your document for review, there is a deafening silence.

You’ve written it but…

..nobody reads it.

I heard a story a while ago about a frustrated Business Analyst who, tired of complaining that nobody read what they wrote, included the text of a novel in the middle of their document. They then sent it out for approval, and sat back to see what happened.

The document was approved without comment.

And we wonder why IT projects go wrong.

But we know where IT projects go wrong – at the start. When the project is asked to deliver slightly the wrong thing to slightly the wrong people. And a good part of why that happens is that even though everyone works hard and tries their best to communicate their ideas, IT ideas frighten business people, and business ideas frighten IT people. They just don’t communicate well.

We’re trying..

For many years, we in the IT world have tried our best to improve our side of the equation. We have stopped using ad-hoc notations and approaches (haven’t we?), and started using standard diagrams and languages. We have even started converging on some standard approaches to development, such as agile.

Agile approaches really do help us to improve our communications with stakeholders. Nothing beats a daily stand-up for getting a whole team to understand each other. But few of us have the luxury of all-agile projects. We still need to collaborate with stakeholders who aren’t able to attend a daily stand-up.

They may be too busy, too important, or too remote in space or time.  So how can we apply ‘agile’ ideas to collaborating with these kinds of people?


“I wouldn’t start from here”

Have you ever been told, when asking for directions to somewhere: “...if I were you, I wouldn’t start from here “?

If you have a 300 page, UML-filled mega-document, and you want to get this approved by your business stakeholders… well I wouldn’t start from there.

At best, you’ll take days or weeks to explain it to them, then spend more days and weeks processing their feedback and creating an updated version. Then do it all over again.

At worst, your document will be approved without comment, and everyone will rejoice at your brilliance, and the project will go forward - on foundations of sand. Because nobody read it, but they approved it anyway because of lack of time, fear of holding up the project, or lack of understanding of the content.


The ideas of Agile – Individuals and InteractionsWorking SoftwareCustomer collaborationresponding to change, are plain common sense.

But even if we are on a non-agile, or partially-agile project, then we can still think how those ideas can be applied.


7 Steps to Agile Documents


If you’re still reading this, then you’re probably on a project which still needs to produce documents. They may be mandated by your company, or the approach your project has decided to take, or they may be a legal or contractual requirement.

Here’s what we think you need to do to start using Agile Documents.


Step 1The Single Version of the Truth.

Putting all your project knowledge into an Enterprise Architect model definitely IS the place to start. This will enable the whole project team to see what is already known, what is still to be done, and how each piece of knowledge relates to every other piece.

This is by far the most important step – without it, you still have the chaos of knowledge being spread around between Word, Excel, wikis, SharePoint, Visio and – the most unreliable knowledge store of all – people.

If your organisation is in any doubt about this, ask them where they keep their own most valuable business knowledge. Perhaps their customer data? That will probably be in a very expensive CRM system, where everyone can see it and use it. Obviously.

We’re just doing the same for IT knowledge.


Step 2 – Documents are for Reading

We have probably all written the 100+ page mega-document, and probably felt quite proud to finally send it out. Job done.

But what about the poor readers? We are probably the only people who understand all the document. Each reader has to find their way to the bits of the document they care about, or understand.  After all, we only have time to write one document, so one document will have to be sent to everyone. Their problem to find their own bits to read.

But if we are generating our documents from a model, we can afford to think more deeply about the needs of each group of readers. We can decide which readers need which bits of knowledge, and then create a family of documents, with overlapping content, so everyone gets a document which is relevant to them, and which they have a chance of understanding.

This is so far removed from the culture of IT organisations that even those who can generate documents from models often take many months to realise that this opportunity exists. When they do, they experience a step-change in their level of stakeholder engagement.

But you can do more….


Step 3 – Reach out and Help

The readers who are least likely to read your document are probably the ones whose input you need most. But they are busy people. They haven’t got time to go through a large document – even one which is customised to their needs. We need to give them every chance to make their contribution by making it as easy and efficient as possible to read their document and give us their feedback.

So, make the document available online – on any platform which has a browser. Then if they have 5 minutes on the train on the way home, they can read the document on their iPad. Or staring at their laptop in a boring meeting, they can review the document, without having to install any clever software.

And we can help them even more.

Not all parts of the document are equally important. If we had time, we would have marked-up a paper copy of the document with tabs to show them where we really REALLY need their input.

Well now we can do that as well. We can mark-up the electronic copy of the document with questions we’d like reviewers to answer. They can then quickly see where we really need then to concentrate.


Step 4 – Collaborate

In an ideal world, we’d get all the reviewers in a room, and go through the document line by line. That way, everyone could hear everyone else’s comments, and we’d reach a consensus.

But we already know that’s never going to happen.


Instead, we can let each reviewer see what every other reviewer is saying – in real time. So they can discuss contentious points. Just as important, once one reviewer has spotted a small error, the others don’t need to bother. Saves time for you, and saves time for them.

And another important collaboration: reviewers might be reviewing the same content in different documents. So, if someone comments on, say, a requirement in one document, the reviewers of another document which has the same requirement will also see the comment in their browser. Magic.


Step 5- Consolidate

At this point, you’re probably thinking ‘how will I cope with the feedback from so many documents’? After all, consolidating the feedback from just one document was hard, especially if there were many reviewers. If you send out 4 documents to 4 different reviewer groups, surely this will be madness?

But now we’ve gone all-online. As the reviewers were creating their comments and answering your questions, all their comments were being saved in your EA model.

So you can see comments being created in real-time, and get involved yourself and add your own comments. And when it’s all over, you can stop any further comments, and everything will be in the model.

So no more consolidation work – it’s all there in one place, with a reference to the EA item which they were talking about. Ready for you to do some real work, and think what changes you need to make.


Step 6 – Iterate

You’ve created some documents, had them reviewed, made your EA changes, now you’re ready to issue a new version.

Now you have an opportunity.

When you created your old 100+ page mega-documents, they took weeks to create and more weeks to review and consolidate.

Now a document takes seconds to create, minutes to review, and a few minutes more to refresh. Why not create smaller documents more often? Like the agile idea of frequent ‘stand-ups’ where stakeholders get involved ‘little and often’.

How about producing a new version each week? Or twice a week? Or every day? If reviewers know it only takes a few minutes to review, they will be reassured that their comments are being actioned, and the project is progressing.

And when they eventually have to approve the final document, there will be few surprises. And the approval gets done electronically as well!


Step 7 – Remember

Remember what?

Remember everything. Remember what the initial Requirement looked like (it’s in the document), remember who commented on it, remember what was agreed, and remember what it eventually looked like.

And remember it for ever, in the same place where the rest of your IT knowledge lives – in your EA model.

So when you come back for the next iteration, we don’t have to go back though our emails to figure out why the requirement looks the way it does. It’s all there. In the model.



Tell me how

The toolset we are talking about here is a combination of the world’s most popular modelling tool – Enterprise Architect from Sparx Systems – and eaDocX Collaboration Edition, an add-on to Enterprise Architect from UK-based Ability Engineering.

For more information, and to experience a live example of what your reviewers will see, visit https://store.eadocx.com/collaborate.


About the Author

Ian Mitchell has been an EA user since v3.5, over 12 years ago. He’s a business analyst leader, mentor and trainer, and speaks regularly at industry conferences. He is also the designer of the popular EA document generator eaDocX, and teaches Enterprise Architect for Ability Engineering in the UK.

As a BA, he's also tired of writing documents which nobody ever reads, so thanks for getting this far.