Good content practices
When you develop your content, always have the user in mind. Follow these simple techniques to ensure that your content is informative, easy to read, and visually appealing at the same time.
Apply these good practices whenever they are appropriate to the functionality that you describe and the type of content that you use. For example, while following a sample scenario through various steps of the process for creating a strategy might make the entire flow easier to understand and apply in other scenarios, that technique might prove useless in a set of articles that outline the testing environment structure. Use these guidelines as pieces of advice about making your content better.For a sample set of articles that put these guidelines into practice, see Creating a microjourney for customer success.
Outcome-oriented approach
Develop content that is focused on the user and the business objective by following these guidelines:
- In parent topics, provide enough background information to allow the reader to make an informed decision whether to read on or not. Provide all the necessary detail upfront, so that users are equipped with sufficient knowledge before they perform the tasks. For more information, see Concept topics.
- In every topic, use the short description to describe why the reader might want to read that content in the first place. Always describe what the users can accomplish through that content. For more information, see Short descriptions.
- Enrich your topics with examples that illustrate how users can benefit from a given task or concept. For more information, see Fictitious information in examples in text, images, and code examples.
- Ensure that your content is build around a common sample scenario. Once you
describe a sample scenario in the parent topic, use this example throughout
the children topics to describe different concepts.
Note: Be careful not to limit your steps and descriptions to cover only the sample scenario alone. Instead, describe all the relevant configuration options that users can adjust to their individual needs. Use the sample scenario only to describe a real-life implementation of a given feature, but include steps for all supported configurations. This limitation does not apply to tutorials, which provide steps for only a specific scenario.
Structure
Provide our readers with a documentation journey that is easy to follow through the following strategies:
- Treat every individual topic as a stand-alone part of a larger whole. Restate some of the information that has already been mentioned in other topics, though with a different level of detail. Always ensure that users know the context of performing a task.
- For conceptual information that is a few paragraphs long, divide the content into meaningful sections with headers.
- Enrich your content with images. Use screenshots, diagrams, process flows,
GIFs, and so on.
Note: Do not include images that do not add value. For example, do not add a screenshot just to show where a field is or how a landing page looks. For more information, see Media.
Navigation
Create uninterrupted navigation through a set of related topics, for example, children of a supertask, by applying the following practices:
- In parent topics, define automatic map links so that all the children and
their short descriptions are listed below the topic. Add a sentence that
introduces that list to clearly describe whether the user has to complete
all of the tasks or just some of them.
Note: Do not use the For more information, see TBD.related-linkselement to list children topics. Use this tag only to list additional reading on similar topics that might be of interest to the user. - For sequences of tasks that are part of a journey, build connections between these tasks by adding pre- and postrequisites with links. Apply the rules that you use for steps, for example, use imperatives and focus on the outcome and business value. For more information, see Content elements.
- Topic elements cheat sheet
Review the following diagrams to ensure that your topics and articles contain the key elements that help us deliver coherent content across different capabilities.
Previous topic Content for a global audience Next topic Topic elements cheat sheet