If you write things people want to read, they will read them.
Let's banish a reductive generalization.
Nobody reads documentation.
These familiar -- albeit unfair -- words are no strangers to the ears of technical writers everywhere. However, while not true, technical documentation isn’t read as often as it should be.
Why not? There are a number of reasons, we mention a few of them here, but the responsibility ultimately falls into the hands of technical writers. Whether you’re a noob, industry veteran, or somewhere in between, we’re going to share some helpful tips that’ll breathe life into your content creation process. We’re confident that these will help you create effective technical content that actually gets read.
Contents:
- The Technical Documentation Lifecycle
- Research Your Topic
- Create Your Documentation Plan
- Consider Reuse
- Identify Gaps in Your Content
- Write, Review, Test, and Deploy
The Technical Documentation Lifecycle
The basic flow for creating technical documentation is probably familiar to you:
Plan, write, review, and publish.
Every organization adds tweaks to this basic workflow to align with their business goals, personnel dynamics, and individual content creation requirements, yet these four pillars are structural mainstays.
We can’t show you how to create technical documentation processes that are bespoke to your organization, but we can give you a solid footing to start from.
Throughout this article, we might mention capabilities specific to Heretto, but the underlying principles apply to all tools. An important thing to note from the beginning is that tools cannot dictate your processes, but they can certainly influence them.
Let’s get into it.
Research Your Topic
When writing product content, it’s easy to fall into the trap of leaning on your own presumed expertise.
Want to know one of the rarest skills in the modern workplace? Asking good questions and then listening for the answer. Technical writers do the tough work, asking the tough questions and the “dumb” questions.
The temptation might be to lean on your own knowledge but be careful. Every assumption carries with it the risk of undermining the entire writing phase. If you make an assumption and you are wrong, the best-case scenario is that it gets called out in the review phase. The worst case is the mistake goes to market alongside the product.
Do the research, ask the tough questions but also ask the questions that seem silly or dumb at the time. It might feel uncomfortable at first, but you need to swallow your pride and talk to other experts.
We guarantee if you think a question is dumb, several other people have had the same question but weren’t brave enough to ask it. Be the brave question asker. The more expert voices you gather for researching your topic, the stronger your content will be.
Finally, if possible, interact with the product as much as you can. While this might not be research per se, it will enable you to ask better, more specific questions.
Create Your Documentation Plan
Don’t be hasty. Layout your plans before putting proverbial ink to page.
A Documentation Plan is an official roadmap that technical writing teams build. It creates a structural outline, procedural consistency, and ensures that everyone is on the same page before getting started. Documentation Plans may differ slightly between organizations, but they share many common elements: scope and objectives, time estimates, workflows, and resources, to name a few.
A common planning document among project managers is the Product Requirements Document (PRD). Your technical documentation team should be familiar with the PRD and there shouldn't be any glaring differences between the key parts in the PRD and your Documentation Plan. Rather than laying your plans separately from the ground up, coordinate your Documentation Plan with the PRD.
In short, the PRD lists what your product does, how it does it, and the more crucial granular details behind it. From the PRD, you’re going to want to look out for things such as:
- Product details
- Audience details
- Details relating to content requirements
- Outputs
- Support
- Constraints
- Releases
- Localization
By no means is that an exhaustive list, but it’s a good start. If you’re looking to go further in-depth on PRDs, check out this article: Product Requirements Document: The PRD Is the Word.
Consider Reuse
How much content does your organization have that is identical or similar enough that it can be reused multiple times in different content deliverables?
When you’ve looked at your content and gauged where you can reuse parts of it in different places, reuse will save you the time-consuming task of replicating the same content over and over again.
In a Component Content Management System (CCMS) like Heretto, you build content in components -- like blocks. Each block can exist on its own as a standalone component. Stacking several blocks together builds a document, a whole piece of finished content. When a block can be used in more than one document, reuse lets you write that block once and use it in multiple places. Then, if that block needs to be updated in the future, it only needs to be updated in the original block, and those updates will populate everywhere the block is used.
Even when you are creating content for a new product, there will likely be a fair amount of overlap with existing products. Find those overlaps and take note. Don’t think of your blocks of content as being limited to a single document, product, or deliverable. This can be a massive time and money saver. Calculating potential reuse throughout your content repository is an initial investment that stands to bear fruitful returns.
Need some help grasping reuse? Piece of cake. Or pie: DITA Reuse, Pie, and How Copy-Pasting Content Is Copy-Wasting Time.
Identify Gaps in Your Content
Good content means whole content, not hole content.
Once you’ve identified the opportunities for reuse within your content library, you have a clear view of the remaining gaps in your content.
Identifying these gaps is a critical step. Think about every component of content as a chunk of road or highway. Your reader is following a predetermined highway of knowledge that you’ve laid before them. Now imagine that suddenly they come to a large gap in the road where there should be a bridge.
Technical content is similar but much more subtle. Getting users to understand a direction is a task that can’t afford gaps. Frustrated users are much more likely to search for answers elsewhere, like YouTube videos and online forums, or search for products elsewhere.
Taking an occasional content inventory is necessary for identifying content gaps that may lead to user experience pain points. What’s more? Users will often straight up tell you where something is lacking, unclear, or difficult to parse. Use their feedback alongside your own content self-analysis and close those knowledge gaps.
Write, Review, Test, and Deploy Your Content
Get it done. Get it done well. Be proud of it.
Finally, the part that you love. Writing. I’m not going to use a lot of space telling you how to do a job you know how to do, just some baseline things to remember when writing:
- Remember your audience and write for them
- Avoid knowledge assumptions about your audience
- Focus on the BLUF (bottom line upfront)
- Be concise, but don’t sound robotic
- Think about tagging any potential variable content (product names, company names, feature names, etc.) that you may need to access down the road
Once the content is written, or perhaps during the writing phase, get the eyes of experts involved. Make sure that during reviews, the right people see the right documentation. Just like finding the right experts during research, you also need to find the right experts during the review phase.
When the right eyes see and review the right content, your job as an editor is leagues simpler. When you’re done there, take a moment to see what your content will look like live. Preview test runs will help identify any remaining errors, however minuscule. Plus, you can see how great your work looks and be proud of it before sending it to the world.
Now, get your content in front of your audience. Heretto’s multichannel publishing capability makes you able to create your content once and publish it to every output your organization uses. Faster, better, easier content that you have every right to be proud of.
