Discourse documentation is currently being reviewed and edited to align with this style guide. Not all documentation topics currently match up to this - we are working toward that as quickly as possible.
This is considered a living document that guides how Discourse documentation is written and formatted. This topic will be kept up to date as needed. If you are in doubt about any of the principles here, please post on the topic to discuss specifics.
The guiding principle behind this documentation style guide is to consider your readers and their needs when writing documentation - what do they want to accomplish? What is your goal for providing the content?
Quick checklist when implementing the style guide:
- Meta block is present and correct
- Title is action-oriented
- All titles use sentence case
- Correct tags and categories are used
- Document is structured logically
When completing a document, review it to make sure all of those criteria are met.
Please take note of these text formatting guidelines:
Meta information
- Document should belong to one and only one of the following categories:
- Using Discourse
- General user guides for non-administrative tasks
- Site Management
- Settings, plugins, content, and general site administration
- Integrations
- Guides for integrating other platforms with Discourse
- Hosted Customers
- Guides that are only relevant to hosted customers
- Self-hosting
- Guides that are only relevant to self-hosted sites
- Developer Guides
- Technical guides for developing on top of Discourse, including creating themes, theme components, and plugins
- Contributing
- Guides for contributing to the Discourse open-source project
- Using Discourse
- Document should belong to one and only one of the following tags / document types:
#how-to#explanation#reference#tutorial
- Document may have any other applicable tags, with an absolute maximum of 5 tags on a single document
Meta block
All documents must have a block at the top that includes a short explanation of what the document is about as well as any additional relevant meta information, like what the user level requirements are, whether console access is required, or anything else. This will be formatted in a blockquote without a heading over it. Heres an example of what this must look like:
This is a guide for describing all available hidden site settings, how to enable them, and why you might want to adjust them.
Required user level: Administrator
Console access required
Titles and headings
- Make document titles action-oriented
- Incorrect: “How to enable automatic titles for chat threads”
- Correct: “Enabling automatic titles for chat threads”
- Document titles should not be too long
- For ‘how-to’ topics, make the title goal oriented
- All titles must be specific and unique
- Do not use punctuation or special characters in document titles, other than commas
- Do not include emoji in document titles
- Use sentence case for titles and headings - that means only the first word starts with a capital letter, along with proper nouns and any other words that would normally be capitalised
- Do not use ampersands (&) in headings, rather use the full word (“and”)
General writing guidelines, tone, and grammar
- Use second-person voice when referring to people reading the document - i.e. use “you”, not “we”
- Use active voice as much as possible
- Incorrect: “the button should be clicked”
- Correct: “click the button”
- Define acronyms and abbreviations when first used, if necessary provide an external link that provides more information
- Use short sentences, and break up text using shorter paragraphs, headings, and lists
- You can use
**bold**and*italics*to emphasise key phrases or words, but don’t overuse them - Avoid using jargon or technical terms without explanations - if in doubt, err on the side of explaining
- Use screenshots when describing a visual interface, such as a UI element
- Don’t document or attempt to disclose future Discourse features, products, or services unless explicitly permitted
- Use transition words such as therefore, although, and furthermore.
- Use common contractions: it’s, you’ll, you’re, we’re, let’s
- Infer timelessness in documentation - avoid words such as soon, new, now, latest, etc. that quickly become irrelevant
- Don’t attribute human qualities to software or hardware
- e.g. “If you pass an integer to this API, it will get angry and raise an error”
- e.g. “Our friendly and ambitious AI bot will help solve all your problems”
- When quoting text (including from the Discourse UI), use “quotation marks”
- When quoting a URL, use
backticks - When using an example domain use
discourse.example.com - If it would be useful, you can use emojis at the start of a paragraph to highlight it. Do not use more than two or three of these in a single topic. Some example emojis you can use:
-
- An informative note
-
- Announcement or notice -
- A warning message -
- Very important information
-
- Avoid:
- Unnecessary metaphors or humour
- Cultural and regional references
- Dictating or ordering procedures in a condescending tone - e.g. You must click Publish or You need to click Publish
- Being overly polite. For example, Please click Publish
- Using exclamation points unless absolutely needed
- Capitalizing words where it is unnecessary
- Excess use of the same phrases and pronouns
For end user documentation:
Maintain a friendly, informal tone, with a focus on being clear and concise in a knowledgeable manner. Get to the point promptly. Explain technical terms, but be careful not to be condescending. To ensure clarity, start by briefly specifying the context of the current topic.
For developer and technical documentation:
Maintain a direct and precise tone. Use the same tone you would for user documentation, but you can assume a higher level of technical knowledge in your readers.
Structure
- Get to the point fast - lead with what’s most important
- Include important keywords early in the document
- Make reader choices and next steps obvious
- Always use light markup to write documentation (This is already built into Discourse with Markdown-it).
- Usage reference: https://markdown-it.github.io/
- Organize your documentation in a logical flow - start with an overview, followed by detailed sections, and a summary or conclusion if applicable
- Use headings and subheadings to structure your content, making it easier for readers to scan and find specific information - use descending hierarchy in headings, starting with h2, and don’t skip levels
- Provide links to related topics or sections within your documentation - this helps users find additional information without unnecessary searches
Links
- Use meaningful text in links
- Unless the format of the URL is important or instructive, don’t use a URL as link text - instead, use the page title or a description of the page
- Link to external sites and sources instead of quoting or rewriting existing documentation
- Ensure that the sites you link to are of high standard and quality
- If the link downloads a file, explicitly mention it - also indicate the type of file being downloaded and a rough estimate of the file size
Code in documentation
- Use block code with language-specific syntax highlighting when possible for large code examples
- If it is not already self-explanatory, introduce a code example with an introductory sentence that initiates the example that follows - when in doubt, err on the side of explaining
- Code examples should follow the best practices for writing code for the relevant coding language
- Use inline code for expressing basic code attributes or when a full code block is not necessary, such as:
- Attribute names and values
- Class names
- Command-line utility names
- Data types
- Environment variable names
- Filenames, filename extensions, and paths
- Folders and directories
- HTTP verbs, status codes, and content-type values
- Query parameter names and values
- Text input
- When you use a placeholder in code examples, commands, or other text, including an explanation for what the placeholder represents
- Write an explanation for the first time you use the placeholder; if there are multiple placeholders or steps after the first use of that placeholder, you can explain the placeholder again
- Provide an easy way for users or developers to copy and run code.
- Show expected output, either in a separate section after the code example or by using code comments within the code example
- Write secure code - never hard-code passwords, API Keys, or secure information in code
Procedures and step-by-step guides
- Format procedures consistently, so readers can find them easily by scanning
- Use a separate numbered entry for each step
- Include actions that finalize a step, such as OK or Apply buttons
- If the instruction appears in the same UI where the action occurs, it’s usually not necessary to provide location details
- If you need to make sure the reader begins in the right place, provide a brief phrase at the beginning of the step
Accessibility and inclusivity
- Use screenshots, diagrams, or videos where they add value, particularly for explaining complex steps or showing parts of an interface
- Images should be used to back up text information, not replace it
- Always use
altattributes for images - Always provide captions or transcripts for videos
- Only use GIFs if you can fully explain the content in text
- Choose simple images and crop extraneous detail
- Use plain language and avoid figures of speech or idioms that might not be universally understood
- Consider that your document will be used on a multitude of devices
- Use gender-neutral language. Don’t use he, him, his, she, her, or hers while referencing people - to write around pronouns, you can:
- Rewrite using the second person (you)
- Rewrite the sentence to have a plural noun and pronoun
- Use the words person or individual
- Use articles the, an, or a instead of a pronoun
- Use a plural pronoun such as they, their, or them, even if it references a single individual
- When you’re writing about a real person, use the pronouns that person prefers
- Be inclusive of gender identity, race, culture, religion, ability, age, sexual orientation, and socioeconomic class - include a wide variety of professions, cultures, educational settings, locales, and economic settings in examples
- Avoid politicised content - in cases where political content needs to be included, remain neutral
- Don’t make any generalisations about people, countries, and cultures, not even positive or neutral generalisations
- Don’t write prejudiced and discriminatory content against any communities, especially minorities
- Avoid qualitative terms related to historical events
- Avoid using terms and metaphors associated with violence and military actions
Last edited by @hugh 2024-09-03T11:02:51Z
Last checked by @hugh 2025-03-10T03:50:30Z
Check document
Perform check on document:
.
). Buen punto sobre la inconsistencia. No estoy seguro de cuál adoptaremos, pero definitivamente nos aseguraremos de elegir uno y ceñirnos a él. 