"About" articles serve as the foundational layer of SUMO. They aim to answer "What is…" questions, helping users understand essential information about our products, features, or services. These articles provide a broad overview or introduce concepts without going into procedural or troubleshooting details.
Table of Contents
When to write an "About" article
You should consider writing an "About" article when:
- Introducing a new product, feature, or service.
- There is a need to explain a concept or feature that is essential to understanding how to use a product effectively.
- There's a significant update or change to an existing product, feature, or service that requires a fresh explanation.
Best practices for writing "About" articles
- Know your audience: Understand that "About" articles are often read by people who may not be familiar with technical jargon or the intricacies of Mozilla products. Aim to write in clear, simple language that is accessible to everyone.
- Start with a clear definition: Begin your article with a clear, concise definition of the product, feature, or concept you're explaining. Avoid using technical terms without explanations.
- Explain the significance: After defining the subject, explain why it is important. How does it benefit the user? What problem does it solve? Why was it developed?
- Provide context: Help the reader understand where this product, feature, or service fits within the Mozilla ecosystem.
- Use examples: Examples can help clarify complex concepts. If possible, include practical examples that illustrate the subject matter's use or impact.
Article structure
- Title: The title should match what the article is about and what the user is searching for. Use sentence-style capitalization for article titles. Limit your title to around 60 characters, as Google typically displays the first 50–60 characters of a title tag. Be concise, yet user-focused.
- Summary: The summary gives a glimpse of what the article is about to help the user decide if they’re in the right place. It should be a textual overview or definition of the concept and focus on why the user should care about the concept. Limit the summary to 140 characters, as search engines may cut off anything longer.
- Body content: Avoid creating long paragraphs and dense text. Use H2 for section headings. Divide the body into the following sections to organize the content into logical groupings:
- Paragraphs
- Unordered lists (reserve the use of ordered lists for “Task” articles)
- Tables
- Graphics (screenshots/GIFs)
- Learn more links: Use H3 for the Learn More section header. It shouldn’t be included in the table of contents. Add unordered lists for the Learn more links and don’t add more than four links to this section.
