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.
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. 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.For more information, see TBD.
- 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