How to get started: writing a User Manual — Technical Documentation
Technical documentation contains a great deal of information about a particular product or a solution. When preparing user documentation/user manuals, we must consider the audience and their requirements. Even if you’re a highly-skilled writer if you cannot convince your readers to follow the document you need to rethink your writing strategy.
As a technical writer for a software product, I get to deal with piles of information all at once. Before preparing a certain document/page, these are the few steps that I follow:
- Try to figure out the big picture
When you are interviewing the SEO, make sure to ask all the correct/wrong questions. Clarify all your doubts. If they have a working demo with them, make sure to have a look. This will be much easier than trying to figure out a set of diagrams. Even if they’re still in the designing phases have a look at their wireframes or any other sketches (if they have any), cause it’s easier to figure out complete flow in a graphical manner — especially when you do not know how the internals work.
Don’t forget to ask for any references that might help you in understanding and creating content as well.
2. Come up with a draft document
Now you have a basic idea! We have answered the major question of “Where to get started?” because now you know. If you ask the correct questions now you will have a rough idea of what type of document is required for this particular feature. Is this a How-to guide, Developer Guide, API Documentation etc. Also, this means you can come up with certain sections of the document.
Structure the document according to your understanding (if you don’t have an SME draft yet). Come up with the sections of the documentation, the topics and certain steps that you think will be important. At this level, you might not have all the resources you require (configurations, UI screenshots, API requests and responses), but you know the flow!!
Fill out the template!
If it’s the same type of documents that you are/will be continuously working on, come up with a template. This will save you time!! Trust me! Make an empty page of the common topics/sections and use placeholders so you can fill them out easily, just a simple template.
3. Familiarize yourself with the feature
If the feature is already developed and available to you, try it out! It makes a world of difference. I have personally noticed how easier it is to document something that you have already thoroughly tested and tried out!! There could be situations where you cannot entirely commit yourself to one feature document and that’s why you need to at least have an overall idea about what this really is.
Think from the end-user's perspective. In most scenarios, you can put yourself in the reader’s shoes as you might be trying this out for the first time. Ask all the questions, note down any hacks you had to perform, check the UX, does the UIs or labels confuse you, play around with the feature as much as possible.
4. Review your work and apply feedback
Now it’s time to review the documentation you’ve come up with so far. Talk to the SME, have a quick chat and review the content, have you missed any vital steps, are these TMI for an end-user, have you understood the use case properly, did you miss out on the configurations etc. Reviewing is the only way to produce quality content.
Once a technical review is performed, do not forget to get your work reviewed from the angle of a tech writer. Does the document fulfil its requirements? does it make sense to a user? is it cluttered with info or not enough info at all? when writing have you used the correct tone? properly followed the style guides? any typos? Get all these reviewed by a colleague because a fresh pair of eyes can notice all these concerns.
After the reviewals, Apply Feedback! This is the most crucial part of this phase. You need to keep an open mind, fix any gaps and polish the final draft. Apply both technical and language reviewals properly. Read your document over and over again.
Tip~ You’ll be able to review your work better if you take a small break from the exhausting writing process. When you’ve completed the review/feedback task, take a small break of a few hours. Remove those rose-coloured glasses and look at the work and ignore the fact that it’s “your” work. You will notice more concerns and bugs this way!
5. Publish! Publish! Publish!
This is the last and happiest step in this process. Now run to your CMS and publish the document. Always remember, you cannot come up with quality content at once and you need to continuously work on that. Consistency is the Key! You’ll receive more feedback from the users once they are published and always be open to feedback.
Note down anything that went wrong during this cycle, make sure to note what went well as well. We cannot unanimously agree on certain documents/structures when it comes to Technical Writing but we can try out different styles and see what works the best.
These are a few of the simple steps that I adhere to these days when creating technical documentation. Things have rapidly changed since now we are working in a fully remote environment yet this process hasn’t let me down yet. But if you have anything to add, don’t forget to share them as well.
