Formatting Guide: Headings, Titles, Images, Links, and Code

--- title: Formatting guide description: Formatting guidelines for technical documentation keywords: formatting, style guide, contribute toc_max: 2 weight: 20 --- ## Headings and subheadings Readers pay fractionally more attention to headings, bulleted lists, and links, so it's important to ensure the first two to three words in those items "front load" information as much as possible. ### Best practice - Headings and subheadings should let the reader know what they will find on the page. - They should describe succinctly and accurately what the content is about. - Headings should be short (no more than eight words), to the point and written in plain, active language. - You should avoid puns, teasers, and cultural references. - Skip leading articles (a, the, etc.) ## Page title Page titles should be action orientated. For example: - _Enable SCIM_ - _Install Docker Desktop_ ### Best practice - Make sure the title of your page and the table of contents (TOC) entry matches. - If you want to use a ‘:’ in a page title in the table of contents (\_toc.yaml), you must wrap the entire title in “” to avoid breaking the build. - If you add a new entry to the TOC file, make sure it ends in a trailing slash (/). If you don't, the page won't show the side navigation. ## Images Images, including screenshots, can help a reader better understand a concept. However, you should use them sparingly as they tend to go out-of-date. ### Best practice - When you take screenshots: - Don’t use lorem ipsum text. Try to replicate how someone would use the feature in a real-world scenario, and use realistic text. - Capture only the relevant UI. Don’t include unnecessary white space or areas of the UI that don’t help illustrate the point. - Keep it small. If you don’t need to show the full width of the screen, don’t. - Review how the image renders on the page. Make sure the image isn’t blurry or overwhelming. - Be consistent. Coordinate screenshots with the other screenshots already on a documentation page for a consistent reading experience. - To keep the Git repository light, compress the images (losslessly). Be sure to compress the images before adding them to the repository. Compressing images after adding them to the repository actually worsens the impact on the Git repository (however, it still optimizes the bandwidth during browsing). - Don't forget to remove images from the repository that are no longer used. For information on how to add images to your content, see [Useful component and formatting examples](../components/images.md). ## Links Be careful not to create too many links, especially within body copy. Excess links can be distracting or send readers away from the current page. When people follow links, they can often lose their train of thought and fail to return to the original page, despite not having absorbed all the information it contains. The best links offer readers another way to scan information. ### Best practice - Use plain language that doesn't mislead or promise too much. - Be short and descriptive (around five words is best). - Allow people to predict (with a fair degree of confidence) what they will get if they select a link. Mirror the heading text on the destination page in links whenever possible. - Front-load user-and-action-oriented terms at the beginning of the link (Download our app). - Avoid generic calls to action (such as click here, find out more). - Don't include any end punctuation when you hyperlink text (for example, periods, question marks, or exclamation points). - Don't make link text italics or bold, unless it would be so as normal body copy. For information on how to add links to your content, see [Useful component and formatting examples](../components/links.md). ## Code and code samples Format the following as code: Docker commands, instructions, and filenames (package names). To apply inline code style, wrap the text in a single backtick (`). For information on how to add code blocks to your content, see [Useful component and formatting examples](../components/code-blocks.md).

This section provides formatting guidelines for technical documentation, focusing on headings, page titles, images, links, and code. It emphasizes clear, concise language, action-oriented titles, and appropriate image usage. The guide also covers best practices for link text and code formatting, with references to examples for implementation.