Complex topics can require long explanations, but sometimes more specific content is more helpful. Break out long articles that cover multiple, related topics, into separate articles when appropriate. On the flip side, long-form content is helpful for things like Getting Started guides and knowledge clusters, where lots of relevant content is packed into one article.
Creating a scannable, neatly organized article is essential to keeping readers on task. Each Docs article contains the same content structure:
Create simple, specific article titles. Readers should have a clear idea of what questions are answered in the article.
- Use title case, except for conjunctions and prepositions. “Price and Plans Guide” not “Price and plans guide”
- Capitalize the names of Help Scout-specific features. “Workflows, Beacon, Docs”
- Capitalize the names of third-party applications.
- Avoid nouns, verbs, and adjectives ending in -ing. “Manage Account Security” not “Managing Account Security”
- Titles are always simple statements, never questions. “Edit Customer Profiles” or "How to Edit Customer Profiles" not “How do I edit customer profiles?”
Article introductions let the reader know what the article contains, or what questions the article answers. Avoid sales pitches and funny catchphrases. If a feature is plan-specific, the introduction is a great place to mention which plan a feature is available on.
A table of contents provides the reader a quick way to find what they’re looking for. Create a table of contents for articles with two or more key points. Link each list item to its corresponding Header 3 text.
- Use Heading 4 for the In this article title text.
- List article sections using an unordered (bulleted) list.
- Add anchor links to each bullet point.
- Use h3 for the individual requirements then explain it as p below
- Use the word 'recommendations' like "Recommendations for creating the perfect bread listing"
- Use h3 and p to explain the significance or unbulleted lists without explanation for recommendations.