At some point in your career, it’s likely that you’ll be asked to write documentation; whether it’s a full business case, or a flier for sharing news or information. Whatever you are asked to produce, there are some key questions to ask in order to best tackle the task at hand.
Our Task
As a Business Analyst, my examples usually revolve around tasks that a BA might be asked to complete – but don’t worry if you’re not a Business Analyst, the questions are applicable to any piece of documentation.
For this example, let’s talk about producing a Business Process Model (BPM). If you are unfamiliar with BPMs, it is sufficient to know that they are diagrams which show the steps involved in a business process – the triggers, order, decisions, and people involved.
We could take many different approaches and pitch at many different levels of detail, but what is the correct level, what is the correct format for the document and what time constraints do we have?
With that in mind, let’s explore the questions to ask.
Question 1: Who is it for?
This first question provides us with a great deal of understanding on how to approach the task. In our Business Process Model (BPM) example, the type of model we produce would differ greatly if the intended recipients were developers trained in Business Process Modelling Notation (BPMN), as opposed to business stakeholders who have never seen a BPM before.
We need to bear in mind the stakeholders’ level of knowledge, the amount of time they will have to absorb to the document and how they will consume it. By consume, I refer to whether they will sit and read at their desks, with no distractions, and be able to fully immerse themselves in the document; or is it intended that the document will form part of a presentation with several other stakeholders. As far as I know, stakeholders don’t usually make a habit of eating documents, but if this happens in your environment then please feel free to consider it (and let me know in the comments)!
Knowing our audience leads to the next question…
Question 2: What are they going to use it for?
Once we know our intended audience, we should seek to understand the document’s purpose. For our Business Process Model, perhaps it is intended that a group of senior stakeholders will use the model to seek clarification on how a process operates at a high level; or alternatively, maybe the model will be used to go out to tender for software contracts to support the underlying process. The document produced would be very different in each of these cases.
If the model is intended for software developers, are those developers looking for a high-level understanding of a process, or are they looking for a model which can be fed into development tools to produce a database structure? Again, very different requirements, each requiring a very different document.
Question 3: Why now?
The third question might sound a little like you’re trying to kick back against the request as a whole, but it is very important to understand why (and whether) there is a requirement to produce this document at this specific time.
Let’s go back to our Business Process Model example one last time. If we are asked to produce a document because it is needed for a workshop in the next few days, this gives us an idea of the level of complexity required and the time constraints involved. We can also infer that this model may evolve into something more detailed during the workshop process, and therefore choose not to produce an overly detailed starting point!
Alternatively, perhaps the model is intended for the same group of people but will form part of the end-user documentation for a product. If we’re early in a project lifecycle we might question whether this is the correct time because as the project progresses things might change, understanding will deepen and our priorities may shift. In this instance, our effort in producing the model may be wasted because we would have to update it to reflect how things actually work, rather than how we thought they might work early on, when we initially produced the document.
Documentation in an Agile World
Although not a direct question, it is worth considering the environment in which you are working when producing documentation. In an Agile world, we prefer “working software over comprehensive documentation”. That is to say, while there is value in documentation, a working product is valued more. This makes implicit sense, as without the working product, the documentation serves little purpose!
Considering this gives us another question: is written documentation the correct medium? We may find, for example, that having an open discussion with stakeholders and roughly drawing an outline on a flipchart pad serves the purpose adequately, rather than writing a fully-fledged document. After all, it’s not uncommon for project documentation to be written, signed off and then never looked at again.
In fact, I’ve seen this happen on more than one occasion, in many different areas! During one assignment, I observed that the project’s file server was stacked with detailed manual testing documents and test code for individual cases, used at a very specific point in the project’s history, and subsequently stored away never to see the light of day again! In an Agile world, we would likely have written automated tests that would form part of the application’s full test suite (to be used throughout the life of the product) after discussing the expected results with the business stakeholders. Choosing the appropriate format for this particular document (or, conversely, choosing NOT to produce a detailed manual test document) adds significant value as the correct outcome from each test will be monitored every time the product is updated. The effort that would have gone into producing manual test documents is redirected into a much more valuable area.
Conclusion
Documents form a big part of our daily lives, and a significant proportion of expended effort. So, the next time you are asked to create documentation, remember the three questions. Before writing this blog, I did just that:
- Who is it for: Business Analysts, Project Managers / Scrum Masters and, in fact, anyone who will be actively involved in writing documents;
- What are they going to use it for: To make better decisions on appropriate documentation, saving time and effort on business projects.
- Why now: Questions around documentation are becoming significantly more common on our training courses. Hopefully this document will provide individuals and their teams with answers to some of these questions.
Recent Comments