Community Docs Guidelines

We recommend using StackEdit to draft your documentation in Markdown.

Writing Style

• Use American English with a clear, concise approach focused on delivering information. Avoid ambiguity.
• Begin with an introductory paragraph that briefly explains what the guide covers.
• Consider how the application or utility will be used and ensure all necessary instructions are included.
• Include direct instructions, and why each step is needed.
• Try and leave as little room for assumptions as possible.
• Use a spell-checker.
• Instructions should NOT be presented as numbered steps, but as bullet-points.
• Read through the guide and ask:
• Does it clearly answer the intended question?
• Can I easily digest what I’m reading if I act like I know nothing?
• Is the information complete and easy to understand?
• Always keep in mind the WHAT, HOW and WHY.

Titles & Headings

• Titles and Headings should;
• be short and concise, preferably under 300px / 35-40 characters.
• be in base verb form (e.g., Install, Add, Configure).
• Exception: Use Troubleshooting when applicable.
• be capitalized, as shown here.
• NOT begin with “How to”.
• NOT begin with “Step 1, Step 2” etc.
• only be H1-H3.
• If applicable, use the following heading structure:
• Prerequisites, Initial Setup/Installation, Configuration and Troubleshooting.

Sentence Structure

• Keep sentences short and concise, with focus on information. Structure sentences in a logical order.
• Use active voice instead of passive voice to make instructions clearer.
• ✅ Click Confirm to install the server.
• ❌ The server will be installed when you click Confirm.
• Avoid vague language. Be explicit about actions and expected outcomes.
• ✅ Execute systemctl --user restart appname to apply changes.
• ❌ Restart the service to see if it works.
• Avoid unnecessary filler words like "just" and "simply." These can make instructions seem less important or vague.
• ✅ Click Save to apply the changes.
• ❌ Simply click Save, and you should be good to go.
• Use consistent terminology throughout the guide. If a button is called Restart, do not refer to it as "Reboot" or "Reset" elsewhere.

Formatting

• Ensure proper punctuation, grammar, and spelling.
• Use hyperlinks for official sources, documentation, or related guides.
• Example: For more details, see the official documentation.
• Bold UI elements such as buttons, tabs, and labels.
• Example: Click Confirm.
• Example: Navigate to the Backups tab.
• Format file names, commands, and code as inline-code.
• Use code blocks for multi-line commands or configuration files.

Screenshots

• We recommend using ShareX or Flameshot to annotate screenshots.
• Resolution: Screenshots must be taken on a monitor with a resolution of at least 1920x1080 (Full HD).
• Cropping: It's acceptable to crop the screenshot to show only the relevant portion, but the final image must maintain the pixel density and scaling of 1080p (e.g., no upscaling or resizing that reduces clarity).
• Ensure screenshots include full UI elements—avoid excessive zoom or unnecessary cropping.
• Annotations: Use arrow markers to highlight buttons, tabs, links, and other clickable elements. Use rectangles to draw attention to fields, text, or other static areas.
• If multiple steps appear in a single image, use numbered markers.
• Annotation color should be red.
• Maintain a 10–20px padding around the focused area.
• Remove mouse cursors, scrollbars, and unrelated tooltips.
• Do not include personal details or copyrighted material. If necessary, use DevTools to hide elements instead of blurring.

• Community Docs Guidelines
• Writing Style
• Titles & Headings
• Sentence Structure
• Formatting
• Screenshots