Writing effective documentation for Discourse

Documentation Contributing
1

:information_source: 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?

:eyes: Quick checklist when implementing the style guide:

  1. Meta block is present and correct
  2. Title is action-oriented
  3. All titles use sentence case
  4. Correct tags and categories are used
  5. 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
  • 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:

:bookmark: This is a guide for describing all available hidden site settings, how to enable them, and why you might want to adjust them.

:person_raising_hand: Required user level: Administrator

:computer: 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:
    • :information_source: - An informative note
    • :mega: - Announcement or notice
    • :warning: - A warning message
    • :exclamation: - 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).
  • 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
    • Incorrect: “Click here to read the guide”
    • Correct: “Read the guide”
  • 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 alt attributes 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 2024-08-06T22:38:09Z

Check documentPerform check on document:
7 Likes
2

@hugh / @SaraDev

I’m seeing a bit of inconsistency here about titles.

We have these examples:

But then we say this:

If I put the “correct” example through the converter, I get this instead:

Enable Automatic Titles for Chat Threads

Should we update our example to match?

aside

If it were just up to me, I’d have thought we’d go with sentence case, and I’m not sure why we have “Chat Threads” capitalized in the current topic title, so I’d personally prefer to see this:

Enable automatic titles for chat threads

But consistency is more important in the end and I’ll assume y’all have a good reason to have chosen the current recommendation.

3

That’s a good catch - I hadn’t made that connection, but it’s easy to update. However:

The title case specification was mine, because I find it generally looks cleaner and more professional. I think that’s very much just my subjective opinion, because both Google and Microsoft say to use sentence case in documentation titles. Other sites I’ve found also say to use sentence case, so I’ll revert this and update the case requirement there.

2 Likes
4

I also notice they say to use sentence case for titles and headings. (I’m on the same team).

Looks like we are not currently specifying our preference for headings. Let’s add that too while we’re at it.

5

Agreed - I’ll add that in here to specify it explicitly.

6

OK, since I’m on a roll here…

I do like that we say this:

But in the guide, we have this example, currently:

My take is that it’s unnecessary to capitalize “Hidden Site Settings” here. (appeal to authority)

1 Like
7

I appreciate the appeal :smile:

Yes, this is a good point - that example was pulled from a real document where we used the title of the existing doc to describe it, and since that doc used title case, the reference did too. With the change from title to sentences case, that reference should also be updated.

1 Like
8

I made a few edits to this style guide now based on the above conversation.

  • Changed topic title to sentence case
  • Changed headings to sentence case
  • Removed an unnecessary capitalization (Syntax)
  • Replaced ampersands (&) in headings with “and”
  • Replaced slashes (/) in headings with commas or conjunctions

Those last two changes weren’t discussed – let me know if they seem superfluous or at odds with the guide (or alternatively, whether we should capture those guidelines in the guide).

1 Like
9

I like those last two - they’re definitely in line with the spirit of the rest of the guide, and they’re worth including in the guide itself. I’ll add them in now.

1 Like
10

I assume flags to label documents in other languages are an exception.

1 Like
11

Along with avoiding idiom, I always avoided using contractions in docs. I thought they made it harder for non-English/non-western readers to understand. English is a weird language.

moreover?

At some point we (possibly me) started using inline code to refer to site settings. For example: “Enable the discourse connect site setting.” That might be the right approach, but it feels kind of developery.

It might be worth using a consistent placeholder name to refer to Discourse sites. Maybe discourse.example.com? There’s some documentation on here that’s referring to the Discourse site as sitename.com. It really threw me off.

Some general writing advice: read what you’ve written as though you’re a member of your (see how contractions are tricky) target audience. Make sure your assumptions about the audience’s prior knowledge are reasonable.

As much as I appreciate no longer having a ton of doc topics ascribed to me, using Discourse as the author of all the team’s doc topics feels a little cold.

What’s made writing fun for me again was the advice to look for ways of putting a bit of yourself into whatever you’re writing. It could be anything, your tone of voice, your hobbies, whatever… That’s kind of the opposite of what’s being recommended here.

6 Likes
12

Heya Simon! :blob_wave:

I was going to see how this played out, but yeah I’m the same way, I try to avoid contractions.

Hahah, yeah… I’m not going to use any of those words in docs, lest I reveal my :face_with_monocle:.

Definitely: Example Domains

This is the point I came here to discuss! :smiley:

We’ve had a lot of back and forth on this, and I was glad to see this included in the style guide by default.

Here’s why I think it is important: producing documentation needs to be accessible for as many members of our community as possible, including (especially?) our Discourse team members.

Discourse is social, discussion software. And some documentation is really an ongoing conversation. If I’m sharing a practice on how I onboard members to my community, I’d want to be presented as the “owner” of that topic, so I may answer questions and expand on the subject.

On the other hand, if a customer asks about a feature that we never got around to explaining, I would like to be able to use the style guide and produce useful, general documentation, which I feel being the topic owner presents more inertia to publishing.

Also, if we produce documentation outside of Discourse (an integration or producing from code comments or whatever), having a “documentation user” is likely easier as a implementation detail. :thinking:

I don’t think this guide will stop folks from injecting their voice and personality, and hosting the discussion. But it would be great if it helps more people get into the practice of documenting, who would not otherwise (and then we can nudge them to be more personal!) :smiley:

3 Likes
13

Until we have a native way of handling localised documents, I think prepending the title with flags is the most practical way to do it, and a reasonable exception to this guideline.

I think this kind of thing has different opinions and preferences either way, but for this style guide we’re going with accepted industry norms. Once again, the Google and Microsoft guidelines both agree that common contractions are better to use.

That being said, I have read some posts suggest that using negative contractions (like “can’t”) might make understanding more difficult for non-English speakers. We’ll dig into this some more and, if necessary, update the style guide accordingly.

I’ve removed that example! :smile:

Yes - that’s very common (not just on Discourse), but I agree that it isn’t quite correct. Using quotation marks would be better, so I think I’ll make that explicit in the style guide.

That’s a great point - I’ll add that in to the style guide!

Thanks for this feedback! @maiki made some good points above, and I agree with what he says there. To add on to that, I will say that one of the reasons we have switched official docs to have @Discourse as the author is to give them a greater sense of authority for readers, especially people coming to the docs for the first time. This is also the impetus behind the whole style guide in the first place.

Anyone writing documentation can definitely still inject their personality into their writing, and the discussion on individual documentation topics isn’t going anywhere, so that’s always a good place to make things more personal too.

All of this feedback is greatly appreciated :slight_smile:

2 Likes
14

Regarding the metablock part of the guide. Although Doc topics need one according to the guide above, not all topics have one [1] and they aren’t always consistent here are some examples from a few guides I’ve found.

Personally I like ‘All users’

I didn’t want to go changing this on topics before gathering some feedback :smiley:

  1. maybe it depends on the context of the topic? ↩︎

4 Likes
15

All the @Discourse docs are being worked on and will all hopefully have one at some point (:crossed_fingers:). Good point about the inconsistency though. I’m not sure which one we’ll land on, but we’ll definitely make sure to pick one and stick with it. :slight_smile:

4 Likes
16

I should also add, that for any you do see with the new info-block included that means they’ve been through ‘phase 1’ and are into the review phase - so if you read one and think ‘that’s not right’ or ‘that’s missing some info’ and are feeling generous enough to leave some feedback please add your thoughts to a post. :heart: :slight_smile:

5 Likes
17

What is the purpose of the required user level information at the top? I thought it would provide information about whether the document is relevant for me or not. So I could read it and decide “I’m not xxx, so not relevant”.
But it seems it is used differently, because for example, users below TL3 can edit wikis, so it’s relevant for others too.

2 Likes
18

Thanks for highlighting that @Moin - that topic has been updated to rectify the user level required.

Your understanding of what that info is for, is correct - it should say what user level or type is able to perform the actions explained in the doc.