How you write is as important as how you structure. Adopting a consistent, clear writing style ensures that readers across varying expertise levels can understand the material, and it helps AI agents interpret it correctly. Some practices include:
Clarity
Prefer plain language and straightforward sentences.
Write as if explaining to someone with minimal context. Use active voice and avoid unnecessarily complex words or constructions (https://maddevs.io/blog/best-practices-for-documentation-in-confluence/ ).
For example, instead of writing “The initiation of the NetWorker backup process should be executed by the user”, write “The user should start the NetWorker backup process”.
Define acronyms and technical terms on first use (e.g., “Single Sign-On (SSO)”) so that anyone (including the AI) knows what they mean. If the subject matter is highly technical, still aim to explain the key points clearly before diving into detail.
Clarity also means structuring sentences so that it’s obvious which thing each pronoun or reference refers to (minimize ambiguity in language).
Brevity
Be concise.
Aim to convey the necessary information in as few words as possible, without trading off understanding. Avoid filler phrases or overly lengthy explanations that could dilute the main point.
For example, instead of a long anecdotal introduction to a procedure, get straight to what the user needs to do.
Brevity helps an AI extract the core answer, if a user asks “How do I reset my password?”, a concise answer in the doc is more likely to be pulled than one buried in verbosity. That said, do include all important steps and context; just don’t pad the content with unneeded commentary.
Tone
Use a consistent, user-friendly tone across all documentation.
Given the wide audience (end users, IT support, admins, developers), the tone should be professional yet approachable. Write in the second person (“you”) for instructional content, as if speaking directly to the user.
For example “You can update the vss-cli settings by…”. This engages readers and provides clear direction.
Avoid slang, idioms, or humor that might not translate well or could confuse non-native speakers (and AI)
A neutral, helpful tone builds trust. For technical audiences (like developers or system administrators), you can be a bit more direct and use technical terminology (assuming it’s defined - Clarity), but still keep the helpful and instructive voice.
Consistency
Maintain consistency in terminology, tone, and style across all pages.
Use the same terms for the same concepts throughout the documentation to avoid confusion.
For example, if one page says “client virtual machine” and another says “user VM” but both mean the same thing, pick one term and stick to it.
Consistent naming helps semantic search match queries to content. It’s helpful to develop a simple style guide or glossary of preferred terms (for instance, decide whether to use “login” vs “log in” uniformly).
Additionally, keep formatting consistent. if steps are always a numbered list, readers and AI learn to recognize that pattern.
Consistency extends to tone.
If your documentation is mostly in an encouraging, guiding voice, don’t abruptly switch to highly formal or terse language on certain pages. A unified style makes the knowledge base feel cohesive and easier to parse.