Handbook Style Guide

The Doist handbook style guide provides editorial guidelines for writing internal documentation. It's designed to help maintain a consistent voice, look, and structure in all our materials.

Use the style guide as a reference for how you'll write documentation, organize information, and customize any visual elements for your team.

To propose a revision to the style guide, click New at the top-left and add your revision.

Voice and style

To maintain consistency in voice, tone, and style in all our documentation, you're encouraged to:

  • Write with a balance of brevity and personality.

  • Use abbreviation to save space (for example: you're, I'm, they're) and write with an informal or personal tone.

  • Use the active voice versus passive voice.

active: Create a reminder.

passive: A reminder is created.

  • Avoid terms that are ableist, discriminating, oppressive, or violent.

  • Avoid idioms, acronyms, or colloquial expressions that may not be familiar to readers who don't speak or write in that language.

  • Avoid writing with a negative or authoritative tone of voice or language.

  • instruction: If you're creating a new Zendesk ticket, assign it to yourself.

authoritative tone: If you're creating a new Zendesk ticket, you should assign it to yourself.

Article types and titles

There are three general article types and corresponding title formats you can use for your docs:

Reference

A reference article provides information or guidelines about a topic.

Reference titles start with "About" followed by the topic.

For example: "About Zendesk"

Task

A task article provides a series of steps to complete a task. It may include a call to action in case you need more help.

Task titles start with an active verb followed by the topic.

For example: "Use TimeTastic to request paid time off"

Troubleshooting

A troubleshooting article provides information about a bug or issue and the steps to resolve them.

Troubleshooting titles start with an "If" statement.

For example: "If a user is locked out of their Todoist account"

Article descriptions

Provide a short description or summary of the topics the article will cover.

When writing a description for a reference article, you can share the purpose of the article to give the reader a clear idea of what they can do with the information:

The Customer Experience handbook style guide provides editorial guidelines for writing internal documentation for the team. It's designed to maintain a consistent voice and structure in all our materials.

Your teammate may have the device you need to test a feature or troubleshoot an issue.

When writing a description for a task or troubleshooting articles, you can start with a verb to give the reader a call to action:

Learn how to respond to these requests or troubleshoot any issues with their promo code.

Learn how to identify user feedback and manually add them to Dovetail.

Headers

An article may have different sections for organizing information. When writing a header, you can:

  • Use a verb to specify the action to take on that topic.

  • Use a keyword if you're providing general information about a sub-topic.

  • Use the name of the operating system or platform when providing steps to accomplish a task or troubleshoot an issue for a specific device or system (for example: Stripe, App Store, Google Play).

✏️ Note

If an article section contains multiple steps, guidelines, or scenarios, you may create a separate article and cross-reference it in other relevant articles.

Organization

Structure and format information to make it easy for the reader to find what they need.

Formatting

  • Use bullet points or * to create an unordered list for guidelines or tips relevant to the topic.

  • Use numbered lists to list steps to accomplish a task or troubleshoot an issue.

  • Add an indent ↹ or four spaces before an asterisk or a number to create a sublist.

  • Wrap guideline keywords with double asterisks or ** to add emphasis.

  • If your sentence involves enumerating three or more items, scenarios, or objects, break the sentence with a colon : and list these items in bullet points or an unordered list using an asterisk * before each item.

  • If you're sharing a list of steps, start each step with a verb.

  • Use tables when you need to compare data. See example.

  • Use relevant emojis when referring to icons in Todoist or Twist, if they're available. Learn how to insert emojis on the Mac or Windows PC. 🔗

  • End the sentence with a period before inserting an emoji.

Quotation marks

  • Use quotation marks "" for user interface elements that use sentence-style capitalization (for example: "Show completed tasks" button).

  • Leave out quotation marks for elements that use title-style capitalization (for example: Filters & Labels) unless it's likely the reader will overlook it.

Scenarios

If there are edge cases that involve additional steps, create a Scenarios section. Don't use FAQs.

Start each scenario with an "if" statement. Then provide the solution or recommendation. For example:

If you've identified a fraudulent payment (header)

If you've identified a fraudulent payment, follow these steps to issue a refund and block the user in Stripe to prevent future payment. (statement)

Appendix

If your article includes templates, steps that aren't related to the topic, or references, use an Appendix section.

In the Appendix section, enclose the content with two sets of three backticks ```. Then, add the link to the appendix to your main steps. [See example](../../Departments & Teams/Customer Experience/Guides/Zendesk/Backlog Weekly Update.md).

Call to action

If the reader has questions or needs more help, add a call to action at the end of your article:

  • If there are two or more internal articles that may be relevant to the topic, add a Learn more header and a bulleted list of article links.

  • If you are linking to an internal or external reference article, use an active verb and insert the link to the article. 🔗

  • If you are linking an external page to an article, add a 🔗 emoji at the end of your link.

  • If the reader needs to ask questions or reach out for help, let them know they can contact the appropriate team in Twist. Avoid assigning a single person as the point of contact.


Order articles alphabetically in a section.