Formatting text in Discourse documentation and UIs

[hugh (Hugh Lashbrooke)]

Discourse UIs and documentation are currently being reviewed and edited to align with these guidelines. We are working toward full alignment as quickly as possible.

When writing for Discourse, take note of the following guidelines for formatting text. These guidelines apply to text in all areas, notably documentation and the Discourse UI.

Capitalisation

When writing documentation or UI text, default to using sentence case (i.e. the first letter of the phrase is capitalised and nothing else).

Important reminders:

• Headings, titles, and category names use sentence case.
• Names of Discourse features are not capitalised, with only the following exceptions:
  • Data Explorer

Do not use any other formatting for feature names, including no bold, italics, backticks, quotation marks, or anything else.

Capitalisation exceptions include:

• Acronyms must always be capitalised appropriately.
• Product and brand names must be capitalised according to their brand guidelines.
• Plugin and theme names must be capitalised appropriately.
• When referring to menu items, button labels, or form options, capitalise the first letter of the first word - e.g. “Click the New topic button to start writing.”
• If something is capitalised in the UI for a good reason, then use that same capitalisation when writing documentation about it.
• Category and URL slugs are always lower case.

When in doubt, use sentence case.

Periods

Do not use a period for the following:

• Tooltips, image captions, or other UI elements with only one sentence
• Button labels
• Menu items
• List items not including a verb

Do use a period for the following:

• Regular sentences
• Tooltips, image captions, or other UI elements with more than one sentence
• List items including a verb
• Image alt text

Caveat for list items: If you are writing a list with mixed items (i.e. some require a period and some don’t) use periods for all of them.

Emphasis

To emphasise words, default to using italics. You may also use bold if you feel it fits the context.

Backticks

Use backticks (``) for inline code, example URLs, and setting names. Do not use them for any other purpose.

Code blocks

When including blocks of code, specify the coding language wherever possible by adding it immediately after the opening fence (the initial three backticks) - e.g. ```css.

Last edited by @hugh 2024-09-09T06:40:35Z

Last checked by @hugh 2024-09-03T11:02:05Z

Check document

Perform check on document:

[Moin]

@hugh

Important reminders:

• Headings, titles, and category names use sentence case.
• Names of Discourse features are not capitalised, with only the following exceptions:
  • Data Explorer

Isn’t Data Explorer a plugin name and because of that covered by

@hugh

Capitalisation exceptions include:

• Plugin and theme names must be capitalised appropriately.
• When referring to menu items, button labels, or form options, capitalise the first letter of the first word - e.g. “Click the New topic button to start writing.”

Why don’t you use the exact spelling of the button? This would make it easier for me to identify it.

This was also done here recently

@kris.kotlarek

Click the “Add Flag” button.

[hugh (Hugh Lashbrooke)]

@Moin

Isn’t Data Explorer a plugin name

That is true, but it felt worthwhile calling it out here, since it’s something of a unique feature in Discourse.

@Moin

Why don’t you use the exact spelling of the button?

We definitely should be using the exact spelling of the button, but the button itself shouldn’t be written like that in the first place. These guidelines apply to all UI elements, as well as documentation. To that end, we will be steadily updating Discourse to align with these guidelines - that may take some time, so until we have done all of that there will be a slight disconnect between the capitalisation in documentation and the capitalisation in the UI.