How do you write technical instructions and guides for different levels of users?

Creating user personas and user stories not only let you improve documentation but also helps to accomplish the golden rule of business “Know your customers and build what they need.” User stories help us to map our user personas in the context of the software or product we are building. This will help you achieve the basic Principle of technical writing which is understanding: “Who is the audience?” You need to understand the audience so that you can write content that is as per their requirement and needs.

This is an easy one, write the first guide in overview terms (this is for General Purpose and Executives). - Revise this one for the Managers with more information. - Revise the Managerial Version and add all the Tech Specs and this is for the SMEs and IT Personnel. That's it - you're done done!

JIT Strategy: A Game-Changer for Every Tech Writer! Users want information exactly when they need it. A Just-In-Time (JIT) strategy is a method that delivers content right at the moment it's required. Here's how to apply: 1. Understand Users: - Identify common tasks or issues users face. - Anticipate when they'll seek help and what they'll need. 2. Modular Content: - Break content into bite-sized, standalone modules. - Ensure each module addresses a specific task or question. 3. Use Searchable Platforms: - Use platforms that allow users to search and find the necessary info. - Consider chatbots, indexed help sections, or interactive FAQs. Remember: JIT is about timely, relevant content. Adopt it, and see user contentment skyrocket!

Start with the base user. Get all of the foundational information captured. Then modify and tweak for all of the more niche users.

An even broader consideration: consider whether readers will really be sophisticated native speakers of the language used in the documentation or might "just" have a basic, but perfectly acceptable, level of expertise. Would they like to read a sentence like the previous one? If not, write short, simple sentences that everyone will understand. Use plain language. Explain and define technical terms when you first use them. Also define them in a Glossary if that is possible and appropriate.

I create a series of step-by-step tutorials, and keep them all in a TOC folder called "How Do I?". These task-based tutorials are targeted for new users. Once these users become more familiar with the application, they can dive in to the rest of the help file, which functions more as a detailed reference guide.

Research existing documentation and verify the documents meet the current customer contract. I discovered there was a poorly translated contract for a large European project. I discussed the contract with the project consultant and discovered that the English translation was word-for-word and not for meaning. The deliverables ballooned from two documents to about eight, with an intervening step for translation to the localized language. After previous failures, we won customer approval for document sets, meeting contract stipulations. To save on translation, use more graphics and write in English for translation. If there is not a standard format, apply an internationally accepted standard that can be sustained.

Don't underestimate the power of formatting to help guide your readers through your document. Using font styles, numbered steps, bullets, and graphics are all great ways to visually guide your users. And, it can help prevent lengthy paragraphs or cumbersome sentences.

Always consider the End User's experience level when writing your documents. Like, for beginners, start with basic concepts and gradually move to the more complex information. Use plain English to break down complex topics to an easier one. Also, provide step-by-step processes and add troubleshooting tips to help users overcome common issues. Format the document properly. Be clear with the point you want to convey and avoid unnecessary information. It helps to keep your End Users on track.

Avoid writing if graphics can provide critical information. Literacy is not a strength for most end users. Make documents quick to read, easy to understand, and memorable. If the reader does not understand quickly and easily, they will not reread the text. I can name corporations that lost customers, market share, and sustained profit, due to poor product documentation. You can, too. Most corporations live and die on customer service, including communication clarity. Do not assume you have put a point across effectively and efficiently. Put your writing through analysis, including everything in the Microsoft Word review toolset. Make clarity and shortness your style. Read it aloud. Ask an intern to read your work.

The best kind of person to review the instructions is the person who's going to have to follow them. I used to work in a laboratory. When I wrote instructions for technicians to follow, I consulted with one of the lead technicians, who was also a good writer. His suggestions made my work a lot more useful.

One of the most productive testing tools for me was the "person off the street" test. I would take someone new to a process and have them work through the guide. The clarifying questions they asked provided valuable insight into gaps and baseline knowledge assumptions. This test worked for all levels of technical documentation; all I had to do was find a candidate with a knowledge or skill level just below the anticipated audience level.

1) I have a virgin end user work through/test the instructions. I want it to be foolproof. 2) I use analytics to look not only at which pages or resources are MOST USED by end users of the manual, but also to look at the search words that they're using. For example, there may be information that end users regularly search for that is NOT (currently) included in the manual. If that's the case, then there clearly is a need or desire for this info on the part of the audience. I'm writing -- first, foremost, and always -- for the end user. 3) I put a "Contact Us" link at the bottom of every page of the manual, and encourage end users to report any inconsistencies or gaps in content, and to submit any comments or suggestions they have.

You can use real-life examples in your testing to make sure your instructions work well in everyday situations. Think from the end user's perspective. This helps find any problems users might have and makes your guides easier to follow and more useful for everyone. This also results in using the keywords the end user would use to find solutions.

Only touch something if you have the time and attention to improve it. Always improve what you touch. Do not waste the reader's time.

When considering your audience, keep in mind that the two most common groups to whom you're most likely to be offering guidance are: (1) those with business experience and (2) those with technical experience. If your audience skews toward the former, they may gain more value from high level overviews that approach the topic from a corporate lens. Whereas for the latter, you might do well to frame those big picture instructions in more technical terms. Commit to one specific audience and don't assume a level of overlap.

Consider, if possible, the longevity of the document and projected documentation support for that longevity. How long will the product, system, or feature be around?

Sometimes documentation needs to address multiple audiences. For example, a user manual for a software may need to provide information for the average user, a power user, and an administrator. A way to handle that is to mark certain sections for the given user role. Chapter 12 is for Administrators only for example.

Write technical instructions and guides for different user levels by using simple language and clear steps for beginners. Include detailed explanations and diagrams for intermediates. For advanced users, provide in-depth information and options for customization. Always organize content logically, use headings for easy navigation, and include examples for clarity.

If you are creating an operations manual or online help system from scratch -- and especially if it is going to eventually be a massive living document -- your number one concern must be: "How do I prevent Chapter One from becoming obsolete by the time I finish writing Chapter Three?" Which is to say, yr primary concern -- after accuracy -- is updatability. (But they are the same issue, because if the content cannot be timely updated as needed, accuracy soon goes out the window.) I've worked in a place where not only laws, policies, processes, & procedures constantly changed, but also, the client would constantly change basic terminology used. This required single-sourcing of content and use of things like user-defined variables.