This module defines the foundational standards for knowledge base content, ensuring consistency, clarity, and usability. It applies to all document types, including release notes, user manual, troubleshooting manuals and multi-media elements.
The following structure is provided as a recommended guideline for organizing content and may be adapted or modified as needed to suit your organizational requirements.
Basic content structure
You can use the following structure to organize your content in the user manual.
Heading & hierarchy
H1: Article title
H2: Major sections.
H3: Subsections.
H4: Nesting subsections (only use if required)
Content guidelines
Restrict paragraphs to a maximum of 4-5 lines. Break content into smaller paragraphs for better readability.
Use bulleted/numbered lists for steps or key points.
Structure of articles
Introduction paragraph
Do not use a separate heading for the introduction.
Directly introduce the feature and its purpose.
Heading hierarchy
Use H2 for major sections, H3 for subsections, and H4 for nested subsections (if required).
Formatting & readability
Restrict paragraphs to 4-5 lines for better readability.
Use bullet points or numbered lists for steps and key points.
Use horizontal line dividers only after H2 sections, not H3 subsections.
FAQ & comparison
Add FAQ at the end of an article.
For comparisons, use the Tabs feature (e.g., SAML vs OpenID vs JWT).
Troubleshooting instructions
If troubleshooting is a section in an article, use H2 as "Troubleshooting."
Add a leading sentence below the H2 heading.
Use H3 for each troubleshooting issue.
The H3 heading should summarize the issue in 4-5 words.
Within the H3 heading, format the content as follows:
Error: Mention the error message the user will see, followed by the cause of the error. If there is no error message, describe the error and its cause.
Solution: Provide steps to resolve the issue. Add a leading sentence before the steps, such as: “To resolve this issue,”
Release notes
You can use the following structure to organize your content in the release notes.
Introduction (No heading is required, just a short introductory paragraph at the start.)
Mention the version number and briefly summarize the overall theme of the release. (Example: “Document360 v x.y.z is now live, bringing new features and enhancements to improve your content management and accessibility. This release introduces new features and improvements to enhance user experience.”)
Features/Enhancements (H2)
H3: Name of the feature (4-5 words)
Category: Module | [Feature/Enhancement] (Font size: 14, Bold)
Summary:
Clearly explain the feature/enhancement in the first sentence.
Describe how the feature/enhancement benefits the user or addresses a pain point.
Provide additional details if necessary.
Callout: Include link to the relevant article. Use the format: “To learn more, read the article on [article link].”
Media:
Provide a screenshot if the update changes the UI.
Use a GIF or interactive demo for complex workflows or animations.
Other updates (H2)
Minor updates that do not require a separate line item will be added as bullet points under this section.
Examples of minor updates: UI improvements, bug fixes, performance and security updates, and any non-critical enhancements.
Writing style & tone
Clarity & simplicity: Use plain language and avoid unnecessary jargon.
Active vs. passive voice: Prefer active voice unless passive improves clarity.
Conciseness: Eliminate redundant words (e.g., use “Click” instead of "Click on").
User-focused language: Address the reader directly using "you."
Terminology & word usage
Standardized terms: Define key product terms to ensure consistency.
Capitalization rules:
Sentence case for headings (except UI labels, feature names, and product names).
UI elements should be bolded and match interface spelling. Use variables for UI elements.
Acronyms: Spell out on first use with acronym in parentheses.
Formatting guidelines
Bullet points vs. numbering:
Use bullets for unordered lists.
Use numbers for sequential steps.
Avoid using bullets or numbering when there is only one item.
Use Bold for UI elements, field names, key actions.
Use Code blocks for syntax highlighting.
Callouts (notes, caution, tips):
Notes: additional context.
Caution: potential risks.
Tips: best practices.
Media guidelines
Screenshots
Use for showing a visual representation of any feature.
Cover the entire screen in the first screenshot of the article to help users navigate to the feature and give them context.
Image alt-text: Required for accessibility. Use AI generated alt-text if required.
ALT TEXT GENERATION PROMPT
Generate concise, accessible alt text for this image in a user manual.Describe only meaningful visual information (controls, labels, states, results).
Be objective, avoid “image of,” include visible text if relevant, and keep it brief (≈ 125 characters) unless longer description is required.
If decorative, say no alt text is needed.
GIFs: In case of any multi-step processes, create short GIFs to show the demo of the process.
File naming conventions: Use descriptive, consistent file names that reflect the product area, task or screen, and media type (for example,
settings-notifications-toggle-screenshot.pngordata-import-workflow-gif.gif).
Capture screenshots and GIFs from the same environment customers use. Ensure no personal information (such as email addresses or profile photos) is visible; if unavoidable, blur the information.
Links & cross-referencing
Internal links: Use descriptive link text (avoid "click here").
External links: Always open in a new tab.