Docs Writing Guidelines

For documentation contributors

This article describes the standards when writing documentation articles for Stackable. We need writing guidelines so that we can present instructions and ideas clearly and in a consistent way to our readers.

Our documentation articles should follow these guidelines:

  1. Use H2 (Heading 2) for titles of major sections. Using H2 automatically creates a table of contents on the right sidebar.

  2. Use H3 (Heading 3) for sub sections under H2 titles. H3 titles should only exist under H2 titles.

  3. Use bold when pointing out words that people see on their screens. Don't use italics or underlines.

  4. Use quotation marks for instructions for entering text.

  5. Use the format: Stackable > Settings (in bold) when specifying admin submenu items.

  6. Show screenshots when specifying areas on the screen that the user will need to interact with.

  7. Use evergreen wording or images. As much as possible, don't use things can easily become outdated.

  8. Don't show unnecessary or unrelated areas in images. Don't show user names, license keys, pricing details in screenshots.

  9. Use proper capitalization for titles. Use a tool like: https://capitalizemytitle.com/

  10. Add Page Links to relevant pages.

✅ Do These

  • Navigate to Stackable > Settings

  • Click on the Activate link

  • Enter "this string" in the text field

  • Heading: How to Install Stackable in Your Website

❌ Don't Do These

  • Navigate to Pages -> Add New

  • Click on the Activate link

  • Enter this string in the text field

  • Heading: How to install Stackable in your website