.jpg)
A stable, predictable, and effective technical writing process is essential for companies looking to produce technical content, such as articles, documentation, ebooks, and other formats, for the long term.
At Wizard on Demand, we write about technical software products and services, and writing well repeatedly is essential for the success of our clients. We have been developing and using a technical writing process from day one of the company’s existence.
In this article, we share our view of how a good technical writing process should work — from early discussions with experts and stakeholders all the way through to publication. In particular, we cover the importance of separate outline and draft stages, as well as how reviewing, editing, and illustration can help you produce great technical content.
Pre-requisites: staff, expertise, understanding of the audience
No technical writing process works without the person to be in charge of the writing. How can you find the right person to do it? You need someone who is technical enough to be able to explain your product accurately, understands your product and customer, and also writes in an engaging and accessible way — which is no easy find!
Based on our experience at Wizard on Demand, your best bet is to hire writers with a background in software development. And you need them to work closely with you from the very beginning to understand what you make and what problems your product solves.
To be able to create the best possible content, the writer will need to give you the opportunity to review their work at various stages. So if you can find a writer who’s good at open communication, this will save you a lot of time and hassle. Even the most technically competent writers in the world will still be new to your product, so you want any misunderstandings about that to be caught and fixed early. That way, more time can be spent on building a productive long-term relationship with them.
If your readers are technical stakeholders, from software engineers to managers to CTOs, it’s very important that your writer understands the hopes, fears, and needs of technical readers, as most technical readers react negatively to the writing that doesn’t meet their level.
One way to achieve this understanding is to work with someone who has direct experience with your audience—for example, someone who has already worked at a similar company—because they already have a sense of what the audience might expect. Another solution is to develop a comprehensive “swipe file” with examples of articles that speak well to your audience. By reviewing such a swipe file, a new writer could get acquainted with your audience quickly. Ideally, you would combine both: hire a person with previous experience writing for your audience, and augment their knowledge with your own, custom resources.
Assuming that you have the right person and you’ve given them enough information about your audience, let’s have a look at the writing process steps.
Process step 1: understanding the subject matter
How should you get started when you need to introduce a technical content writer to your topic for the first time? You might already have a strong idea of what articles you want them to write. Or you might be feeling at a loss as to how to begin.
Either way, the best way to start is with a conversation. In our case, we ask detailed questions in order to understand the client’s product, the purpose behind the article, and the intended audience. One of the key things we’re looking to take away from this conversation is the exact kind of person who will read it, so we can pitch the article at the right technical level. Here are some example questions that you can include in this conversation:
- What is interesting about this product feature that you’re planning to release?
- How do customers accomplish this task today, without this feature?
- What would you like the reader to do after reading this piece, ideally?
- What’s the unique viewpoint that you have on this topic?
Once the questions are covered, we suggest that you decide on the article title (even a provisional one) and a few key points to cover, to facilitate the following steps.
Advanced tip: come into this meeting prepared with some competitor research. Analyze what other articles exist on the topic, what’s great and not so great about them, and how you can use it to your advantage. Consider how you're going to promote your new article too: an SEO-focused article might be structured differently from a piece designed for promotion via social media or PR.
Process step 2: writing an article outline
If you want to ensure that any mistakes or misunderstandings are identified early, then you need your writer to provide an article outline at an early stage. An effective outline allows you to see the structure that will guide the overall organization and flow of the article. Our outlines contain section titles, bullet points that explain the key information to be covered, and, if you require it, a Call to Action.
Your initial conversation with your writer should clarify many details about what will be a useful and relevant article structure, so you shouldn’t expect many surprises at the outline stage. At Wizard on Demand, we don’t skimp on the details when it comes to parts of the article or aspects of your product that we’re unsure about – we err on the side of making assumptions and writing them down, but then letting the client identify and correct any inaccuracies early.
Internal peer review of the outline by a technical writer colleague helps get it into a complete and polished state, as it enables the writer to address any glaring errors and make necessary modifications. You can then review the outline and provide feedback, so that the writer can incorporate any comments into the article draft.
Process step 3: writing the article draft
One of the most valuable traits in a technical writer is the ability to ask the right questions, and to ask them early. It’s a good sign if your writer asks questions about your intended readers before starting to write their first draft – such as who they are, their level of technical expertise, where they’re located, and even their job title. This enables the writer to pitch your article at the right level for your readers, instead of writing something generic. A good content marketing writer also uses this stage to clarify important details such as the required word count or whether there are any SEO keywords that need to be included.
A skilled writer uses their outline as a guide, and adds more detail as they write the full article. This results in an article that’s clear, concise, and pitched at the right level of technical difficulty for your reader to get the most from it. To keep your readers engaged, the draft can include some technical illustrations or screenshots that can explain the most complicated parts of your article – one picture is worth a thousand words!
If you’re planning on publishing your writing online, for example as a blog article, consider how linking to other pages from your article will impact the reader’s experience. For example, having too many links can confuse the reader, and linking to the websites of direct competitors might feel odd. Not including relevant links can also have a negative impression on the reader—for instance, to pages with more information about the topic you’re covering, or with related products or services that you offer.
Anything that saves your writer time ultimately saves you money. It’s more efficient for your writer to think of this first draft as the final draft, to ensure they give it the care and attention it needs. However, once the draft is completed, you’d be amazed how an internal review process as well as the services of a technical editor can lead to a polished and high-quality article. If, instead, you have a writer who skips these steps and tries to work alone, this is likely to lead to errors in both content and writing style. You don’t want to waste your own time keeping an eye out for small mistakes, and you also don’t want to worry about errors being missed, as every word on your website is valuable in conveying the value and integrity of your brand.
Process step 4: finalizing the article
Before the final article is sent to you, you want to be confident that your writing team has remembered to check the basics: your article needs to be plagiarism-free, it should contain all the important metadata, and all links should be functional and accurate. Also, any internal discussion on the article should be completely resolved – you don’t want to publish an article only to realize that your CEO disagrees with the points made in it.
Speaking of administrative tasks, you might also want to hand off some of the post-publication tasks surrounding your article. For example, you may need to launch a social media campaign to share the article with relevant readers, or post the piece to industry forums, Reddit or Hacker News.
Technical writing process at Wizard on Demand: organization, openness, and clarity are key
From our experience, by breaking down our writing process into specific and detailed steps, our writers and staff have a clear understanding of their responsibilities and deadlines. This level of quality could never be achieved by one person alone.
To ensure that we complete all the necessary steps of your article in order, we have created subtasks in Asana for each step of the process. This helps us to keep track of important tasks such as running an automatic plagiarism check (which can be super helpful for avoiding unintentional repetition of other articles — including your own!). Using the same set of subtasks for each article ensures that all the articles we write follow the same series of steps. By completing all subtasks, we can be confident that your article is of a high standard.
Our organizational improvements, combined with our open communication style and fail-fast approach to catching issues or inaccuracies early, have made our technical writing process much smoother. Our writers and editors are much happier as we now have far fewer major issues, and our clients love the quality of the articles we produce!If you're interested to find out more about writing great technical content, you can read our article about the best ways to collaborate with us, or get in touch for a free consultation.
