Every software project should ideally be accompanied by comprehensive technical documentation, detailing all the inner workings of the codebase, and explaining the software’s architecture, design choices, and coding conventions.
As such, they’re highly useful documents and invaluable assets to software development teams.
However, how do you begin your documentation project? How do you organize the writing process?
A great place to start would be composing a technical documentation plan: an outline of the documentation writing process.
If you need guidance about doing just that, don’t worry—this article is for you. Keep reading to learn how to write a stellar technical documentation plan.
Identify the Target Audience
The first step to creating a high-quality technical documentation plan is determining who you’re writing for. Who is going to read the documentation plan?
For example, there’s a significant difference between writing for product managers within the company and external stakeholders.
The former are likely familiar with your company’s standard processes and workflows, whereas the latter could be entirely new to these concepts.
On the other hand, imagine if your documentation plan was written for your team of technical writers.
It could then be pretty informal but perhaps more detailed than if it was intended for upper management.
To pinpoint the target audience of your documentation plan, ask yourself the following questions:
Whatever employees and colleagues come to mind when answering these questions will probably be interested in the documentation plan.
As such, tailor it to suit their viewpoint and expertise.
That being said, there’s also technical knowledge to take into consideration. How comfortable are your readers with jargon? Will they understand common software documentation terms?
These are all essential factors to appraise when composing your documentation plan.
However, as a general rule of thumb, it’s best to take professional writer Jory MacKay’s advice:
The golden commandment of technical writing is: “Thou shalt not assume.” You might think you’re being obvious, but you have to be aware of the knowledge level your audience is at.
In other words, you should be mindful of their technical proficiency.
If there’s even one possible non-technical reader, it’s best to err on the side of caution. Explain acronyms, avoid abbreviations, and take your time with technical concepts.
The readers of your documentation plan will appreciate it.
Outline the Scope of the Documentation Plan
After identifying who you’re writing for, it’s time to determine what you’re writing about. What will the documentation plan address? What subject matter is obligatory to include?
Conversely, are there any topics that can be omitted?
To put it another way, you’ll need to outline the scope of the documentation plan.
For example, will you compose a general document applicable to all projects, or is it custom-made for one specific project?
Will the documentation plan cover testing documentation along with standard technical documentation?
Just defining these parameters is hugely helpful for your technical writers. Knowing the scope of writing is half the battle; with defined guidelines, the actual writing process should be quick.
Harvard professor J. Richard Hackman thinks so as well:
Often the key to work processes is simply knowing what is expected.
If your technical writers know the established scope, they can be more productive when composing the documentation plan.
And they aren’t the only ones who benefit from this knowledge. Why not also communicate it to your audience?
That way, they know what to expect and can easily judge if the plan will benefit them.
Tuck professor Scott D. Antony also advised relying on this practice:
Insert a table of contents or write a scope statement at the beginning of your documentation plan.
This brief piece of writing will inform your readers of precisely what is included in the documentation plan, and they’ll be able to quickly judge if the document can be of use to them.
Create an Outline for the Documentation Plan
Now that you’ve defined the scope, you can finally structure your documentation plan. The easiest method is to create an outline; a rough draft of how the content will be organized.
Such an outline ensures the documentation plan will be logically arranged. There won’t be any arbitrary subject changes, and each section should intuitively follow one other.
When constructing the outline, try following the inverted pyramid methodology.
This approach is an information architecture strategy that first spells out the most important insights, then branches out into details, and lists minor information last.
Here’s a visual representation:
In the context of your documentation plan, the base of the pyramid would probably constitute the document’s purpose, scope, and goals before delving into the particulars.
Then, at the end of your documentation plan, you could include a glossary, referenced bibliography, and similar—the tip of the pyramid.
For more ideas on what to incorporate in your documentation plan’s outline, look at the graph below. It displays all the standard components of a documentation plan:
At the minimum, your documentation plan should contain the sections listed above.
They’re included in most documentation plans and are a good starting point for outlining your own document.
Furthermore, the visual follows the inverted pyramid structure.
The essential information (cover page, contact information, summary) is covered first, after which the document delves into finite details, such as the technical document specs.
By following these guidelines and suggestions, you can easily create a stellar documentation plan outline.
Decide on the Right Format for the Plan
Once you’ve defined your documentation plan outline, you have to decide how to present this information. What font to choose? Are bulleted or numbered lists better? Will you use diagrams?
There are countless ways to display information, so you must pick the optimal format type for your documentation plan.
The easiest place to start is typography. Generally speaking, the two font families are serif and sans serif, both displayed below:
The serif font includes decorative tapers, whereas the sans serif consists of clean lines without ornaments.
Because of its straight lines, sans serif is considered more formal and is commonly used in business. Consequently, this font is preferable for your documentation plan.
If your company is relatively modern, you could use serif fonts for the body of the text, but the headers should remain sans serif.
That way, the document’s chief signposts will look professional.
Regarding the content itself, consider incorporating diagrams.
Sometimes it’s better to convey information visually (rather than through the written word), as readers usually process images easier than text.
For example, Cloud Architect Lynn Langit utilizes diagrams in her documentation.
Here’s how:
I've had good success with diagrams. I customize views for audiences, i.e., customer-flow view, developer view, DevOps view, etc. Also, I like to color the areas of the diagram Red | Yellow | Green, to quickly show status.
With user-friendly elements such as color and customization, diagrams make your documentation plan much more accessible.
For example, imagine describing the document review process. Wouldn’t it be easier to illustrate the stages of this process via a diagram rather than writing out every detail?
As you can see, deciding on the right format for your documentation plan can make a world of difference.
Evaluate the Available Resources
With the format type established, your next task is determining your documentation capabilities. In other words, you should evaluate the writing resources available to you.
The visual below shows an overview of these resources:
Your human resources are arguably the most crucial factor, as you need to know who can contribute to these texts.
For example, how many technical writers do you have? Can they cover the workload? Are there any developers who can help out?
Who will your subject matter experts (SMEs) and reviewers be?
Answer these questions carefully, as they indicate who can influence the documentation directly.
Regarding technical resources, first evaluate your hardware.
Do your servers have sufficient disk storage and memory? You’ll likely use high-powered tools like Visual Studio Code and Adobe Photoshop, so these technical specifications are crucial.
After the hardware, verify your available software. Which tools will you be using? How will you take screenshots? Which spell-checking software is best?
However, first of all, ensure you have a high-quality documentation tool. Such solutions are crucial, as they greatly facilitate the entire documentation process.
For example, here’s a snapshot of Archbee’s features:
With Archbee, you can create your own documentation website with a custom domain so your company brand shines through.
The website can host multiple products, and there’s robust version control for each document.
And that’s only the beginning; Archbee also provides access control, Markdown writing, collaborative editing, and countless other features.
With a resource like this, you can easily create beautiful technical documentation.
Write the Technical Documentation Plan
Since you’ve now determined all the available resources, you can finally begin writing the documentation plan.
With so much preparation, you likely want your documentation plan to be as thorough as possible. However, these texts are most effective when short and sweet.
If your documentation plan is too long, there’s not much chance anyone will read through the entire document, as there’s only so much time in the day.
Furthermore, it’ll be more difficult for readers to navigate, and they might miss important information.
You might be worried that a shorter documentation plan won’t provide all the necessary intelligence—don’t be.
This topic was discussed in a Reddit thread, where one user mentioned the following:
If the documentation plan isn’t detailed enough, readers can simply ask you for clarification. The documentation plan provides context; the nitty-gritty particulars can always be further discussed.
You might even edit the documentation plan after one such conversation, as maybe your colleagues have some insight you hadn’t thought of. In fact, documentation plan writing is usually done in iterations.
Take a look at the graph below, as it displays the typical documentation plan writing process:
The documentation plan should be reviewed twice before beginning your documentation project.
Furthermore, the document can always be rewritten if there are any changes in your documentation approach.
As such, writing your documentation plan will rarely be a linear process, but the document is an invaluable resource for your documentation strategy.
Review the Plan and Revise It if Needed
Finally, the last step of writing a documentation plan is reviewing your work. It’s a good idea to take one final look at your text, evaluating if everything is correct and logically structured.
Before doing so, give yourself a break. Don’t immediately begin examining the text right after you finish writing; take time to rest.
That way, you’ll look at the document with fresh eyes and are more likely to spot inconsistencies and mistakes. You’ll always have better judgment when feeling refreshed.
However, ensure you reserve enough time for a thorough review, as you don’t want to rush such an important process.
According to experienced technical writer Jean Weber, this is the typical editing estimate:
If your documentation plan is twenty pages or less, reviewing it shouldn’t take more than an hour. However, if it’s longer than that, reserve at least two hours, just in case.
To make the job easier, multiple online grammar tools can help you out.
These resources will evaluate your spelling, punctuation, and grammar for you, so you don’t have to worry about linguistic rules.
For example, Grammarly is a popular tool that analyzes all these elements. Here’s what it looks like:
The tool highlights any sentences that could be improved, and offers a replacement immediately.
With this resource, you don’t have to check your spelling or punctuation; the tool will review those elements independently.
Conclusion
Writing a technical documentation plan takes a little bit of time, but it’s well worth it in the long run.
With a properly-constructed documentation plan, you and your technical writers will know exactly how to proceed with your technical documentation project.
The plan will guide you along the way, giving you a constant reference point to fall back on.
Such a resource is sure to facilitate documentation writing, and the entire process should be quicker and more efficient.
Your documentation will ultimately be of higher quality, and your team of technical writers is sure to thank you.
See how Archbee's features can help you create and deploy your technical-documentation with our free trial.
