Spark Content

We often meet with companies who want help updating their existing documentation. Sometimes, someone has kept up with some smaller changes. But, other times, the documentation has fallen far behind the software. So, they decide to call in the experts – us!

One thing about hiring experts – we’re thorough. We often identify changes, beyond the software, that could improve the content. Most are minor, such as updating titles to make sure that they accurately capture the user tasks or identifying wording consistency issues. But, sometimes we uncover broader issues, such as content that doesn’t address user needs or content that is missing important information. These changes take longer to address and can come as a surprise to the company, especially if they have been keeping up with smaller updates.

Here are a few reasons why a company’s documentation might not be as complete as they think that it is.

Starting with information meant for a different audience

Software projects are often under tight timelines and documentation updates are usually the last thing on the to-do list. Pressed for time, it’s easy to copy the relevant information from other project documents and make the basic changes. Some changes are easy to spot – such as turning descriptive paragraphs into numbered steps. But, others aren’t as obvious. For example, it’s harder to break away from the existing structure to look at it from the user’s perspective. So, even if the copied text is edited to make it more user-facing, the structure of the original source still dominates. Often, the source information doesn’t follow the order that users would complete the tasks in. Without seeing tasks in their natural order, it’s harder to spot what information might be missing. Other times, a single task is created, rather than splitting information into multiple tasks. Because there is so much information there, it’s hard to see what isn’t there.

Not looking at all the existing documentation

Incomplete updates are also a result of the iterative nature of software development. Because software updates usually focus on a specific part of the software, it’s tempting to narrow the focus of the documentation changes to the immediately impacted topics. Individually, the targeted updates seem reasonable and complete. But, over time, these isolated changes lead to a fragmented or inconsistent guide. By ignoring the larger documentation piece, isolated updates can overlook or exclude related information that could help users accomplish tasks more easily.

Without looking at the complete task flow in a document, isolated updates can also lead to odd workflows that jump around and confuse users. They can lead to procedures that are near-duplicates of one another, without enough information to distinguish between them. This duplication can mislead users – they don’t know which task to follow and ultimately might have them looking for information elsewhere.

Those iterative updates might be done by employees who specialize in a particular aspect of the software – and who focus on a particular content deliverable. No one is looking at the entire content set. Someone updating the user guide might not realize that there are FAQs that address the same issue. Again, duplication abounds and users are confused.

How does your documentation stack up?

Before a company updates their documentation to add new or changed features, they should take a step back and think about whether the current content addresses their users’ needs and whether it is as complete as it can be. If it’s not, they might be creating the documentation equivalent of a Jenga® tower: a large pile of information with tiny holes in it that creates an unreliable base for their users.

Because we look at documentation with fresh eyes, we are more likely to spot issues. If constraints don’t allow all changes to be made at once, we can recommend the most important ones to shore up your documentation and support your users. With our years of documentation expertise, the writers at Spark can fill those holes and make sure that you can continue building your documentation on a stable base.