This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- WordPress
- Technical writer:
- dmivelli
- Project name:
- Improve Article Discoverability in WordPress HelpHub Documentation
- Project length:
- Standard length (3 months)
Project description
Executive Summary
The popularity of WordPress grows by the minute. As of early July 2020, WordPress 5.4 (the latest version released on March 21, 2020) has been downloaded nearly 51 million times. The most commonly used language is English (71%), followed by Spanish (4.7), and Indonesian (2.4).
Great technical documentation is the backbone of any help system. Experienced technical writers craft knowledge into content for users. The users are looking to perform some action that is of value to or required of them at that time. Good technical writers understand that well written, accurate documentation and the ability to place themselves in the mind of the user are essential. What may matter most to a technical writer though, such as editorial and production quality, may matter less to users than timeliness and discoverability. What good is a beautifully written help topic if the user can’t find it?
Since its start in 2003, WordPress’s growth in the Open Source arena has attracted developers, users, and contributors. The original article categories and tags need updating and modernizing to keep up with the growth and changing needs of the WordPress community.
When the users’ paths to the requested documentation are confusing or interrupted, they fail in their search, lose trust in the product, and may ditch it altogether.
There is a solution. The following are ways to improve discoverability and support the user path to the expected documentation:
- Decide and set the style for category titles
- Evaluate category titles and ensure they correctly address the topics (propose updates, if necessary)
- Review the articles and ensure the categorizations are correct
- Define subcategories for each article
- Ensure that no search results guide the users to support forums
- Note duplicate or outdated topics for deletion
The WordPress community has completed remarkable work and share in the accomplishments of the last 17 years. To update the categorization and ensure the user journey is accurate will continue to boost the growth, success, and loyalty of the users who create nearly 70 million new posts and 77 million new comments each month.
Introduction
Author Joseph Campbell coined the term, the Hero’s Journey. In fiction, it refers to the structural concept where the protagonist journeys into the world, faces and overcomes challenges, and returns transformed.
In the technical documentation realm, the user also embarks on a journey – one that takes them to the help topics with the goal of learning, getting answers, and troubleshooting. When the user can accomplish this, all is well in their world. When users cannot find answers, they leave frustrated and disheartened.
But, why does this happen? It’s not because the writers cut corners, don’t care, or don’t have the know-how. Often, it’s that the technical writer didn’t consider the user journey. Writers might immerse themselves in creating good content but fail to consider how the user will access the topic. Focusing on the user journey is critical. We must consider what they want to know and how they want to get there.
I spoke with WordPress Consultant and UX Designer Estela Rueda, who provided some history. At present, some titles do not correctly describe the article content. Categories are used as tags and because they were created 15 years ago, some are outdated. Tagging is inconsistent. This creates obstacles for users looking for answers.
Current State
WordPress Support is divided into nine main categories (Getting Started, Installing WordPress, Basic Usage, Basic Administration, Customizing, Maintenance, Security, Advanced Topics, Troubleshooting). Each category contains several sub-categories or sub-topics that lead to articles with the possibility of more at each landing page.
The benefits of having enthusiastic, collaborative WordPress contributors is that many topics are available. With many voices and points of view however, tagging and categories are inconsistent.
These topics needs modernizing to ensure that the categories meet the current needs of WordPress users. With more than 200 articles, the issues with tags and categorizations has become relevant.
Plan Analysis
The main goal is to review and reclassify articles to improve searchability. I propose the following steps:
Work with Mentor Estela Rueda to solidify process
- This is an important step to ensure details are confirmed and agreed upon
- Per Estela, we will track all proposed updates in a spreadsheet (Estela’s experience has shown that it’s best to gather and then, propose recommendations)
Decide and set the style for category titles
- I suggest a uniform, consistent structure for the categories in the present tense instead of the gerund form (Install vs. installing), as the gerund form (-ing) can create difficulties for English as a Second Language (ESL) users and the -ing doesn’t add value to the user
- Some categories are one- and two-word subjects (such as Maintenance, Security, Basic Administration) and some are gerund phrases (Getting Started with WordPress, Customizing) – it makes sense to discuss making the structure consistent
- I’ve been researching how other organizations set up their online help and will discuss this with my mentor to see what might be useful
Evaluate category titles (and propose updates)
- These should be recognizable to the WordPress target audience’s perspective and suit their current needs
- Confirm that they are consistent and adhere to the WordPress Style Guide standards
- Ensure titles convey/explain intent
- Titles should clarify any required pre-requisite actions or user/device states
Review articles/topics
- Do the topics accurately meet the user needs of the WordPress target audience?
- Do topics set the correct context or are they part of a larger sequence?
- Do the steps distinguish the various actors in the task (user, system/device, who does what)?
- Are the actors clearly distinguished?
- Do the steps break complex processes into actionable chunks?
Define and tag subcategories
- Refer to the user stories and keep adding to the spreadsheet for future reference
- Keep adding to the list of subcategories and detail their path
Ensure that no search results link users to the support forums
Note duplicate or outdated topics for deletion; this forensic work will help inform and streamline user journeys
Timeline
Through August 16, 2020
- Continue reviewing WordPress documentation
- Become more familiar with the WordPress documentation style
- Research best practices for customer journeys into help topics
August 17 – September 13
- Get to know and work with Estela and the WordPress community
- Collaborate with Estela to refine the project steps and suggest milestones for completion
- Create a schedule to include milestones and weekly tasks
- Set a cadence for a status check-in with Estela (to address any blockers in a timely fashion)
September 14 – November 30
- Project kick-off and development work with Estela/mentors
December 2-5
- Submit Final Work Product Report
December 3-10
- Submit project success evaluation and evaluation of experience working with the WordPress mentors and team
Conclusion
WordPress is the most popular content management system (CMS). According to W3techs, WordPress is the CMS of choice for 37.7% of all websites - giving WordPress a 63.6% of the CMS market share.
With this degree of popularity, accurate, easy-to-follow documentation is a must to win the heart of the WordPress user.
By taking into account the user journey and the questions that inform the possible user paths, WordPress can modernize the help categories and tagging to effectively answer questions and troubleshoot issues. This way, WordPress will continue attracting satisfied customers for years to come.