How do you balance the trade-offs between simplicity and completeness when updating documentation standards?

When writing documentation it is helpful to start with a spreadsheet outlining the main points with the supporting information.

Determining your target audience may be tricky but doable. There is always a great divide between the person signing off the document and the actual users. Among the users the level of understanding and comprehension also varies. This is where using plain language can be of value in bridging the gap without losing the quality of the document.

I look at the user's workflow using the application/tool, and see if I have all the tasks covered. Then I look at troubleshooting to see if there are any common errors that I can document solutions for. After that, I turn my attention to the presentation of the information. It needs to be easily scanned if in text format. My goal is always to present the content so that the user can return to work as fast as possible.

To keep a fresh perspective, I like to step into the end-user's world and look at how my documentation works for them. Just like people, documentation and User Assistance (UA) is ever changing and dynamic. What worked 3 years ago for my audience may not work today. People read less and watch more. In-app UA is more prevalent with the latest apps. I consider how something will render in a mobile app. I often search for new technologies on how to present and publish content. About once a year I compare my content to that of our company's Website and marketing content to ensure I'm using correct, consistent, or new terminology. And last, but not least, I constantly cut words. (Ironic coming from a writer, huh?)

This decision is made much earlier in the process. You need to decide what the user experience should be and find the tools and delivers that. Then consider the budget, skills required to author, and the technology needed to deliver the content.

Most of the time, you won’t have any choice when it comes to tools. That choice will be made for you because most companies already have Microsoft Office installed on all their laptops and desktops. It’s when dealing with software companies, you’re more than likely to see different tools like GitHub, Framemaker, Flare, etc.

Having a standardized structure that is clear and concise to your documentation will help solve customer pain points of relaying important information. With the onset of AI, you can automate the structure quicker and showcase to a client so that they can provide feedback.

After meeting with the project manager, stakeholders and SMEs to gather requirements and answer key questions about the audience, use that information to create a table of contents. Once it’s created, have another meeting with the decision-makers. Review the table of contents with them and then get their sign-off on it.

Word is a great tool for creating documentation styles. In addition to having common tools to check grammar, spelling and punctuation it will allow you to create almost a limitless number of styles for the headings and subheadings in your document. It can create Indexes and Table of Contents. The Track Changes feature will allow you to review edits from other contacts. The Navigation Pane is an easy way to reorder the document if necessary.

Make agreed upon choices for your documents. Decide whether to use the serial comma, then use that punctuation consistently. Always define three letter acronyms before using them in a document. Decide whether to use he/she/they or not. For example, "the user" can be utilized. Consider whether to follow recognized documentation style standards such as ANSI or IEC.

Documents must follow a lifecycle. This will help one do a schedule or periodic review and evaluate the usefulness and relevance of the document in the constantly changing business environments. Changing laws or regulations may also affect the value of the document.

Try to "future-proof" your technical documentation by limiting the number of product screenshots or images that will need constant updating. Limit the number of links to third-party websites to help streamline your updates. Use a tool that will help you check for broken links. Maintain style sheets and templates so your content doesn't look like a collection of pages haphazardly thrown together. Make sure internal and external users can provide feedback and have a plan to quickly make changes so users will continue to provide feedback.

Balance simplicity and completeness by focusing on essential information first. Use clear, concise language to ensure understanding. Include detailed sections as needed, but keep them separate for advanced users. Regularly review and streamline content to maintain clarity while ensuring all critical information is covered. Prioritize user feedback for continuous improvement.

Definir personas pode te ajudar a adequar a linguagem, deixando-a nem t?o complexa, caso seja um público leigo, nem t?o detalhada (leia-se chata), se for um público mais técnico.