The Problem with our Documentation
We have a problem with the majority of our documentation as Software Engineers: when we do decide to write documentation, it tends to end up overly complicated, full of jargon, and unfocused. We spend hours on end trying to make sure we write the cleanest code possible, yet put very little thought into how we write our documentation.
One way to put more thought into our documentation is to simply spend more time on it. The issue is, at most companies we aren't given the time to do this - good documentation doesn't necessarily produce the short-term results that a business looks for.
Rather than spending time scrutinizing every paragraph and explanation you write, consider the following approach. Before writing anything down, spend 10 minutes doing some planning and determine a baseline and a scope for your documentation. This planning can not only make the writing process easier for you but also help the reader make the most out of your documentation. Let me elaborate.
Set a Baseline
Perhaps one of the hardest parts of technical writing is identifying the skillsets of your audience. You can publish a page to your team or organization, and have no idea who is going to end up reading it. Imagine writing some documentation on a very niche topic that builds upon many other concepts within your team's ecosystem. A seasoned veteran reading this will likely have no issues understanding your writing. However, what if a newbie to the team stumbles upon this documentation and tries to read through it? Suddenly, the documentation has done the opposite of what it has intended to do - the various jargon and implied knowledge throughout your document ended up making the topic more confusing for the reader, rather than less confusing.
A baseline of knowledge is the minimum amount of information required to understand the information you write in any given document. Before even beginning to write documentation, write out a bulleted list of all topics that you will assume are known by your audience. Place this bulleted list at the top of your page in its own section - perhaps label this section as "Baseline".
Here is an example baseline I would set for a page on learning Redux:
# Starting out with Redux
## Baseline
- Knowledge of React, particularly in: components, state, lifecycle, hooks
- Functional programming concepts: pure functions, side effects
- Immutability
Defining a baseline at the top of your page does a few things.
It makes it easier to write. By defining a baseline, you define a minimum set of knowledge that is now implied. You no longer have to describe any details of any of the topics you listed within the baseline. Technical jargon now becomes more helpful rather than confusing - I can now use the term "pure function" when describing a reducer in my Redux page, and be confident that the reader will know what that means. This allows me to be more concise.
It makes it easier for the audience to understand your writing. Now that there is a clear expectation set at the top of the page, a reader can evaluate how much they already know. They can choose to read up on these topics before continuing on with this particular document, rather than blindly diving into a piece of documentation. Once they are ready, they can come back to this documentation equipped with the knowledge they need to read through your explanations.
It identifies gaps in your ecosystem's documentation. Now that you have written a baseline, you can go through each item and link them to other resources and documentation to help the reader learn. This has the obvious benefit of making more documentation accessible to the reader, but it also helps to identify certain subject matters that are lacking in documentation. Note these subject matters down as future candidates for more documentation.
Set a Scope
Certain pieces of documentation try to cover too much at once. It is easy to separate topics at a macro level. Consider writing a set of documentation that will cover the entire animal kingdom. An obvious place to separate pages of documentation is between the different animals. We will write a separate page for a Bengal Tiger and another for the Northwest African Cheetah. This distinction is clear, but will we really be able to contain all information about the Bengal Tiger on one page? Likely not. We could write a page on the hunting habits of the Bengal Tiger, and another on their habitats. Even these topics might be too broad. Separating topics on a micro-scale is nuanced and often subjective, but ultimately important to keep your writing clear and concise.
A scope is the subject matter that your documentation will cover. Like with setting a baseline, you should set a scope for your page before you even begin writing it. Define a few bullet points that describe at a high level what your page will be about. Place them under the baseline section on your page, with a header named "Scope".
Here is an example scope I might set for the Redux page I mentioned above.
# Starting out with Redux
## Baseline
...
## Scope
- What problem does Redux solve?
- Application Structure
- The Store
- State, Actions, Reducers
Like defining a baseline, this accomplishes a few things for you.
It helps you divide on a micro scale. The act of outlining your desired scope for a page forces you to consider what content you include on the page. If you notice you have many topics listed under your scope, consider trying to break them up into a few categories and divide that content across multiple pages. Too many items within a scope can lead to long-drawn-out documents. Oftentimes, readers will have an easier time digesting information if it is broken up into clear discrete parts.
It keeps your writing on track. Now that you have a set of bullet points that outline what the page will cover, you have a defined starting point to start writing from. Pick a bullet point and start writing. Again, if you notice a particular topic starts to drag on, consider splitting it out into its own page with a baseline and scope of its own. The scope also defines a clear end state for the page - once documentation has been written for each item in the list of scope, then you know you are done. A well-defined scope keeps your documentation concise.
It signals to the reader what the page will cover. If the reader reads the scope and determines that this page does not cover what they need to learn, they can leave immediately and not waste any of their time reading the page. If the scope does cover what they would like to learn, now they know exactly what to expect from this page. Setting expectations upfront with the reader gives them a clear idea of what they are getting themselves into when sitting down to read your documentation.
The Takeaway
Defining a baseline and a scope are two easy and time-efficient ways to instantly improve your documentation. It aids tremendously in the writing process while giving the reader valuable information at the same time. Perhaps you already internally think through these two aspects before writing a page. Putting your thoughts down on paper like this brings that planning to another level - you are already thinking it, so why not put write it down?
This physical contract keeps the writer true to their original plan. It acts as a set of guiding principles that keep you the writer on topic. When a baseline is defined, there is no need to explain details of Topic A to the reader - they already know about it. When a scope is defined, there is no need to write any more or less than what is dictated by the scope. These two simple lists go a long way towards making your documentation more clear and concise.
If you've enjoyed this content, consider subscribing to my mailing list to be notified whenever I release new content.
Top comments (11)
Really like the Baseline idea, which could also answer the question "Who is this document for?"
The "Scope" looks like a Table of Contents, which a Wiki could autogenerate.
I would add that a "Takeaway"/TLDR section at the end of any document (what you did here!) is really beneficial.
Two very good points - you’re right in that a Wiki could auto generate the scope/table of contents, I just prefer to write it out myself ahead of time to give myself an idea on what I’ll be writing.
The takeaway idea is great! I’ve never thought of adding that to technical documentation - will have to experiment with that a bit more.
In the technical writing business, baseline is known as audience analysis.
Once one has settled on an audience, the next step is to determine the general contents of the docs. If the project output is a product, you'll need a basic outline like the following:
Despite the order of chapters, one typically starts with the lowest-level reference first.
Document all inputs, outputs, errors.
If one has time, create a simple example for every function.
And so on.
To really improve your documentation, hire a technical writer. But beware, you'll need to spend time bringing them up to speed, so don't wait until too late in the development cycle.
If the budget allows, also hire an editor (or contract editor if the project is short). The more eyes on docs, the better.
Thanks for sharing - as a Software Engineer I am far from a technical writer. I have never been fortunate enough to work with a team that hired a technical writer - us engineers have had to take it upon ourselves to write documentation and this is part of the method I've come up with when I go to write documentation. Having a dedicated technical writer sounds like a dream!
Very focused and on point. Any good literature you can suggest on documentation and concepts like these?
I have honestly struggled to find many good books on documentation from a Software Engineering perspective. There is a lot of literature and content out there around "Technical Writing" from a general perspective that you could look into. I personally have not read too much in this area since none of it seems applicable to my job as a Software Engineer.
That being said, here are two excellent books that look at writing documentation from more of a Software Engineers perspective:
I also plan to write a whole lot more on the topic, looking to publish a post weekly. So, you can also stay tuned for that!
Thanks for the two links I will definitely stay tuned as I currently see the benefits of documentation with onboarding my juniors
Google has a course about technical writing, it is a good starting point
developers.google.com/tech-writing
Helped me a lot! Thank you so much
Glad you enjoyed it!
I always found this talk very useful: youtube.com/watch?v=t4vKPhjcMZg
Also see: documentation.divio.com/