Formatting best practices
Table of Contents
For larger articles with multiple sections, use a table of content. With Timelapse, table of contents can be generated automatically from H2 tags in an article.
When to use Bold
Use strong/bold formatting to designate:
- Buttons: Click the Submit button;
- Drop-down menus and items: Select Many from the Options drop-down menu.
- Paths: Go to Support > Account > Billing.
- Checkboxes: Select the User and Administrator checkboxes.
- Notes, Tips, Warnings: Note: This option is no longer available.
Steps and procedures
Ordered lists make it easier to read a procedure or step-by-step instructions.
- Click on the New button
- Write a title
- Click Save
When relevant, include images within lists
Images and attachments
- Avoid using images and screenshots for obvious procedures, e.g., Click Next, Continue, OK.
- Use a caption when possible to provide context about the image.
- When only a small portion of a screenshot is useful, zoom that portion specifically.
- Annotate images with callouts when applicable
Quotes and code
Use the available Quote and Code formats, it makes such content much easier to read.
Some clever quote.
def some_function print "code block" end
How did we do with this article?