"How-to" article type best practices

“How-to” articles answer “How to…?” questions and help readers understand the steps to accomplish a specific goal or procedure. They break down the complexities of our products and services into simple, actionable steps, making every task manageable. "How-to" articles serve as the practical companions to our foundational "About" articles. While "About" articles introduce users to the concepts and significance behind our features, "How-to" articles take users by the hand and walk them through the actions needed to harness those features to their advantage.

When to write a "How-to" article?

Consider turning to a "How-to" article when you're:

• Introducing new features or products: Whenever we launch a new product or introduce a feature, it's crucial to provide users with a roadmap to its functionality. Write a "How-to" article to guide users through the setup, usage, and optimization of these new offerings, ensuring they can make the most out of them right from the start.
• Enhancing user experience with existing features: If there's a feature within our suite of products that users are not fully utilizing due to complexity or lack of knowledge, it's a prime candidate for a "How-to" article. Create detailed guides that unlock the full potential of these features, empowering users to enhance their experience and productivity.
• Solving common issues: When users face recurring issues or errors, a "How-to" article can be a lifeline. Develop articles that address these problems with step-by-step solutions, helping users to resolve issues on their own. Focus on breaking down the resolution process into clear, manageable steps, making sure to address common pitfalls and questions along the way.

Best practices for writing "How-to" articles

Creating effective "How-to" articles requires a blend of clarity, conciseness, and comprehensiveness. Here's how we approach it:

• Step-by-step guidance: Break down the procedure into clearly defined steps, ensuring users can follow along without guesswork.
• Visual aids: Include screenshots and inline images to visually complement the instructions, making complex steps easier to understand.
• Tips and warnings: To give users a smoother experience, highlight potential pitfalls to avoid and provide tips for best practices.
• Related content: To guide users beyond the current article, provide recommendations for additional resources at the end.

Article structure

• Title: The title should match what the article is about and what the user is searching for. Task article titles should start with an action-verb, but avoid using gerunds. You should also avoid using article titles containing “How to…”. “How-to” titles should be task oriented, while “Troubleshooting” titles should be problem-centric. Use sentence-style capitalization for articles. Limit your title to around 60 characters, as Google typically displays the first 50–60 characters of a title tag.
• 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 task and focus on the importance or benefits of the task. Focus on real, user goals and not product function. Limit the summary to 140 characters, as search engines may cut off anything longer.
• Body content: The body contains the breadth and depth of information required to diagnose and resolve the problem. It may also contain results and examples. Add a Table of Contents section at the beginning of the article if you’re documenting multiple sets of related steps. Use H2 for section headings. Lead with the objective before documenting the steps (i.e. “Change your password”).
  • Pre-requisite (optional): Add any information or actions the user should know or do prior to completing the task.
  • Context (optional): Add any conceptual information or background information.
  • Steps: Use ordered lists to document the steps and actions that must be taken to complete the task. Avoid using nested steps.
  • Result (optional): Add the expected outcome after completing the set of steps.
  • Example (optional): Add any examples to support the task.
  • Post-requisite (optional): Add any information the user needs to know or do after completing the task.
• 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.

Examples

• Clear browsing history in Firefox for iOS