Often, it's helpful to group information in context to help people complete a complex task, understand a set of related tasks, or illustrate an entire workflow. Use longer articles combining content types to ensure people find contextual content in the right place. Longer articles also help eliminate duplication of content and prepare content to scale as more options are added to the product. People most often need longer articles while actively using the product, and they may need to consult the article at different points on their journey.
How to combine multiple content types in an article
- Use conceptual, procedural, referential, troubleshooting, or known issue content in a longer article, and do not use quickstart or tutorials.
- Use sections of different content types in the article as needed, and follow title guidelines for the content type.
- Most often, these articles will contain at least one procedural section plus at least one additional conceptual, referential, or procedural section.
- Use the content ordering guidelines to organize headers within the article.
- Use troubleshooting information as frequently as possible.
- You can replicate the article’s title in a header if needed.
Title guidelines for articles that combine multiple content types
- If there is a procedure within the article, use a task-based title that begins with a gerund.
- Titles are general enough to describe the range of information and tasks contained within the article.
- Titles describe the setting being toggled and are agnostic about what setting the reader chooses, e.g., "Setting repository visibility” instead of "Making a private repository public.”