Documentation Best Practices

You’ve learned all about how to use our new Markdown editor, you’ve walked through our new page controls experience, you’ve understood the differences between the types of pages, and now you’re wondering: How do I make a doc that is performant, accessible, and meets my users needs?

We’re so glad you asked! We’ve gathered some suggestions to support you creating docs in our new editing experience that are all of these things. Check out below, and get in touch with any questions!

Performance

We built our editor with you and your users in mind! To that end, we recommend keeping these best practices in mind when writing your docs.

A few suggestions:

• Keep documents well below 400 lines. This ensures your editing and user experiences are as smooth as possible. Plus, it means less scrolling down endless pages for everyone!
• If your document is longer than 400 lines, try breaking it up into multiple pages or subpages so it’s more digestible.
  • Example: if you have a document with different steps that’s getting long, break those steps up into subpages and take advantage of our What’s Next feature to guide your users through the optimal flow!
• Use the Markdown editor whenever possible. Editing in raw mode increases the possibility of encountering hard-to-track-down errors, and the new editor makes for a much nicer writing experience!

Accessibility

To make sure your docs can reach as many of your users as possible, it's important to make them as accessible to both humans and machines! Here are some suggestions along those lines:

• Use the caption and alt text features on images so all users have more context and screen readers can access images.
• Write concise and descriptive titles and excerpts for your pages! This will make searching within your docs easier for users as well as ensuring your docs are easily findable via browser searches. Check out this page for additional tips and a detailed walkthrough on how to update this metadata.
• And remember: keep your docs short, sweet, and on a single topic!

Finally, if you’re ever at a loss about where to start, feel free to use our docs as inspiration! We've worked hard to make them detailed yet concise.