Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/
Join our discussions of documentation issues here on the blog and on Slack.
Exploration of a new classification for user documentation
While working on a new design for HelpHub or documentation in WordPress.orgWordPress.orgThe community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/, we discovered that the implementation of a menu or a table of contents was difficult because the articles were included in several categories.
Documentation is maintained manually by contributors and it is being moved from the old Codex. The structure is 17 years old and as WordPress develops and grows, the categories that worked 5 or 10 years ago are not necessarily the same that work now.
In order to continue with the design of documentation, we need to define a documentation structure that is clear and fulfills the user’s needs.
Problems with the actual categorization
The issues below affect the way users consult the articles in the documentation section.
There is a lack of definition of user personas.
Search is not user-friendly because navigation is not clear, making article discoverability challenging.
Inside a categoryCategoryThe 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. with several pages, articles jump order, making navigation confusing.
Some titles are not descriptive enough or use only one word.
What are we looking for
It is important to define first what the goal is for the documentation structure in order to define the categories. Envisioning what our ideal documentation section should look like:
It should be easy to navigate: a user should understand where they are.
Categories should be broken into subcategories to ease mobile navigation.
Categories should be descriptive enough to quickly answer the question: “where does this article go?”
It should be reliable: if an article is not found where it should be, it means that the article simply doesn’t exist
Titles should be descriptive enough for any type of user to understand what the article is about.
Maintenance or updating of the articles should be easy with a clear documentation structure
The structure should allow the incorporation of new categories or subcategories as the software develops.
The docs team worked on creating some stories that can help us verify if the proposed solution will work. You can find the complete list of stories here:
If I am new to WordPress, how do I know if it is the right CMS for my project?
If I am a blogger who receives many comments, is my data secure in WordPress?
If I am not a developer, can I still create a website and add my own branding?
If I am a business owner, can I sell products in WordPress?
If I am a website designer, where can I find information about new releases and upcoming features?
What documentation looks like now
So far, there are 171 articles being moved from Codex into HelpHub. Separately there are new articles being written about the blockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor, so far 40 articles have been added and there are plans for more.
In the image below, we can see a snapshot of how articles are included in several categories. At the moment, the articles were arranged in alphabetical order because the articles jump order while scrolling through the pages:
Let’s review an example from the image above where the articles jump order inside a category with multiple pages.
In the video below, we are looking at the category Getting Started. A session was recorded following the Next Page link at the bottom of the page and then returned to the first page following the Previous Page link. The first page at the beginning has different articles than the first page that we returned to.
What it is like on a computer
The first page begins with the following list of articles:
Appearance Menus Screen
Backing Up Your WordPress Files
Pages Add New Screen
New to WordPress – Where to Start
Administering Your Blog
Resetting Your Password
Creating a Search Page
We navigated to the last page via the Next Page link at the bottom of the page and then returned to the first page, using the Previous Page link.
When arriving to the first page, the list of articles is different from what we have above:
Comments in WordPress
Creating a Static Front PageStatic Front PageA WordPress website can have a dynamic blog-like front page, or a “static front page” which is used to show customized content. Typically this is the first page you see when you visit a site url, like wordpress.org for example.
Users Your Profile Screen
Settings Writing Screen
Giving WordPress Its Own Directory
Settings Reading Screen
What it is like on mobile
On mobile, the situation is the same.
Looking into the future
As mentioned before, the end-user of documentation is not well defined but the existing documentation can shed some light into identifying who the users are.
Who is the content intended for?
From the stories written, we can identify some groups, but we have not explored the many user personas that access the documentation. Here are some examples:
New users looking for a CMS to build a website.
Bloggers/website designers that want to customize a site.
Content creators looking for content to write tutorials/posts.
WordPress consultants that provide services to their clients.
Type of content
In order to define a navigation structure that suits the project and allows for growth, we need to explore information pillars. Pillars shouldn’t be more than 4 or 5, as these can be split into categories and subcategories to form a logical navigation structure. These are suggestions for information pillars: