How can you write clear technical documentation?

When determining your audience, build personas based on an understanding of the tasks they need to complete, and focus on problem areas. Do not use marketing demographics like age, cultural background, and household income. Technical documentation must be designed to answer a reader’s question in their critical moment of need. Also, content should provide multiple layers of depth to help the more experienced readers in the audience to quickly find a workable answer, yet lead readers to learn more if interested.

Above all things you need to make the documentation accessible. So many times I've been reading a technical article and it leaves out giant gaps in the process. Especially with developers (and all of us) there are blind spots where you assume others will just fill in the information. But for someone reading the documentation they might need the absolute "start from scratch" and explain each detail mentality. I don't see this done too well often making most documentation a 'piece' but not the whole pie. You end up having to find multiple articles to gain context. So add the full context and related steps to build the best documentation you can. Think as a total newbie, not as an experienced developer.

The audience reading your content could be technical or citizen developers. The audience can be a beginner or an advanced user. Your article should be drafted in such a way that it provides information/ learning point to all types of audience. Keep your audience in mind!

Technical writing is simple and tricky. My first and foremost rule is to avoid using jargon and geek-english. Keeping it comprehensive to everyone. The second rule is switching the boots so I become the reader I intended to write for. The third rule is starting from a universal point rather than just starting from a particular. Let's take the example you are telling the user to open the command terminal in windows (cms). I'd write him to press the Win+R key pair on the keyboard from any window you're working on and then type "cmd.exe" The fourth and final step is to run through the guide yourself or ask a friend. Always go for detailed technical support and assume that the user is non tech.

Creating clear technical documentation is vital for conveying complex information effectively. Tailor content to your audience's understanding, employ logical structure with headings, and offer context for relevance. Be concise, use visuals like diagrams, and provide step-by-step instructions. Real-world examples enhance comprehension, while consistent formatting and whitespace improve readability. Prioritize clarity, define technical terms, and gather user feedback for refinement. Implement version control, ensure digital searchability, and keep language accessible. These principles empower you to craft documentation that empowers users and enhances their experience.

Documentation has to be properly designed. Define your standards and create the right structure for the documentation, depending on the project you're working on. For example, consider requirements and prerequisites, a quick start guide, tutorials, and how-to guides, and.. especially don't forget about the glossary!

draft and plan a strategy flow of the topic you writing. gather all the relevant data (Pictures, screenshots with arrows dictating) that is important for the users. Use symbols to justify method of information like "Informational, Warning, Tips"

Aim, Method, Results = Conclusion. You can always hypothesize the case scenario however lead to the conclusion, always add references of any source information rather than 'go it alone'

Crafting clear technical documentation demands thoughtful structure. Plan like an architect designing a blueprint. Outline key points, a roadmap for readers. Organize logically - beginning, middle, end. Each section a pillar supporting understanding. Use headings, signposts guiding the way. Break content into digestible chunks. In this framework, clarity finds a path, and readers navigate with ease.

Imagine you have the reader on the phone. They are on the verge of panicking because they need to perform a task and there is only very little time left to get it done. How would you phrase your instructions? Exactly! You would give instructions in strict chronological order, using short sentences with consistent phrasing and vocabulary, as if you are writing a script. The reader must be able to "make the movie in their head". Als make sure to use a calm tone of voice, and to build in sufficient checks and verifications to keep the reader reassured they are doing it right.

Always have someone try and follow what you have written and ask them to 'pick on' what is not clear or concise. Keep mindful that everyone reads things differently if something is missing, learn from them and correct.

I agree that clear is a requirement but sometimes concise is not the best approach for technical documentation. The best approach is "as little documentation as you can effectively communicate with". In some cases I want more information, more examples and more context. But the content needs to be in plain and easy to understand terminology. Using analogy and examples really helps to set the context as well. I hate to see the tiny little paragraph on a feature that barely states anything about the function, it's just way *too* concise. Give me enough that I can go from A -> B effectively and understand how I got there.

In my experience "Plain English" is much easier to understand especially when reading longer documents. Good resources on that include The Economist Style Guide, "Plain Language Writing Tips" on archives.gov and the Plain English campaign.

Read the information that you are creating, double read it to make sure it makes sense, triple read it to have no doubt the work is done coreectly. Use tools to ensure your spelling is correct and the tone that you are using goes hand and hand with the material. Read it out loud and you will get a good perspective how your document will be taken.

Make sure the images are clear and in focus. Make sure they are relevant to the wording. Make sure all figures are numbered correctly and included in the Table of Content (ToC).

Do not use too many images: layouts and UIs can change over time, so use images only where necessary. Avoid GIFs, as users may lose focus. Prefere, instead, a PNG image and bullet points, describing a process.

Providing examples of the expected output of a task or piece of code allows your user to compare their results to yours, to validate that what they produced is correct.

I have found that sharing edits from people that read documentation are able to be kept within an addendum this not only aids the document but also assists the readers' questions.

I would also suggest adding expected input examples as well, sometimes especially with shell scripts it is not very clear what to pass in input and if this script doesn't have a header with example if takes time and effort to understand it. So adding input examples in such cases can be very helpful.

The primary goal of technical documentation is to make it easy for users to understand and utilize the technology or information you are presenting, the most important is , everyone has to be able to use it as their first hand on document, not only for certain user but it has to cover all level of users so the test part has to be ensured to reach all users

I would not say that bad but updated documentation is better than a looking good but obsolete one but... Obviously, it has to be at least understandable, but if it takes ages to write a "beautiful" one, so that once it is written it is already obsolete, maybe it doesn't worth it

You should also consider building documentation from code repository so it will always bee up do date. You have a lot of tools that can build a document based on your code, and then you can add things if necessary. This way you'll save a lot of time by not doing constant updates manually.

A good way to keep your documentation up to date is to create a process for it. You could update some parts of the documentation through the source code repository. If so, make sure also to create automatic regression testing for it like ”it’s not empty”, ”it exists”, ”it has at least following sections”. Another method is to reserve time each quarter to review some documentation. Or if it’s more lively document like a runbook for incidents, maybe it should be updated monthly for the latest information. Gather a group of individuals who spend a predefined time doing so regularly.

Documents should be reviewed in IT - every update, so being realistic, every 3 to 6 months if it is 1 year old it needs to be re written in most cases.

Use Knowledge Centered Service methodology to produce, update & maintain the KB content needed to drive self service and case deflection.

I like to bounce drafts off another pair of eyes to make sure I'm making sense in my documents. Sometimes it's an experienced pair of eyes, sometimes it's a new hire. I struggle with making my documents look as good as the pros, but I'd like to think my specific audience is just looking for a quick reference and not a full on tutorial. My other issues are sorting through and finding the right document as my category folders sometimes blur into each other. I sometimes wonder if I can ChatGPT'ize my content.

research and create a documentation plan.?You need to gather relevant information from reliable sources, such as books, journals, websites, experts, or experiments. You also need to organize your information into a logical structure and outline the main topics and subtopics you will cover in your document.

In addition to all of these fantastic insights above. Keep it simple, adding insight where ever possible. For example, add a notes section with your own additions, in areas you know are more difficult. Use practical examples in words anyone can understand. Remember where your journey began, you weren't always the expert.

Any documentation that is to be published should be reviewed and approved by more than a single person. Especially for technical documentation, the author alone should never be the single source of truth. Having a subject matter expert and other authorities verify the documentation will ensure the most accurate results.