Update on the revision of documentation

This article is part of the Help Hub redesign series. Previous articles on this project at listed at the bottom.

As previously established, the Help Hub articles have problematic navigation as they are now. There are numerous reasons why that has happened but the new plan focuses on better use of categories.

As of now, there are 9 main categories and some articles have 2 or more categories making the navigation confusing. Another issue is that the landing page does not contain a table of contents per se, instead shows links to some articles.

The plan is to create 4 pillars and add categories to each pillar. Because this work is not done, there will be another post with more details. Let’s talk about the articles.

The proposal for a new navigation includes reading, reviewing, and classifying each one of the 170+ articles on Help Hub plus the articles for the blockBlock Block 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.

What are we reviewing?

  • Content: what is the article about? wherein the website creation does it fall into?
  • Codex links: are links still directing to a Codex page? does that Codex page still exists or has been migrated (without updating the link)?
  • Information: is the feature/process/tool described/recommended still valid or are they outdated?
  • External links: are links up-to-date or are they too old? is the link directing to a 404? flag all external links for docs team review.
  • Structure: are there too many links in the same paragraph? is the article following the new style guide (wording, headlines, punctuation, etc.)
  • Code snippets: are they well structured? is the code complete? are they needed?
  • Images: is it a good example? is it the latest version?

We feel that the revision is not exhaustive, but we will be as detailed as time and resources allow it. The work is being tracked on a spreadsheet because it needs to be reviewed by different contributors:

The process

The revision of articles began as a project under the 2020 Google Season of Docs. The assessment done by the GSoD technical writer included title changes and suggestions of merging/deleting pages with repeated or similar content. @dmivelli also came up with a first navigation proposal.

As a designer, I am reading each article to understand the documentation structure and can propose logical navigation, and at the same time, making recommendations on outdated content, structure, flag links, and image updates.

@atachibana from the documentation team is commenting on my recommendations, finding new links to replace flagged links and revisiting outdated content.

We still need the review of a developer to check on the code snippets and other technical information we are not familiar with.

Before making any updates to the articles, the documentation team will have a chance to have a final assessment.

We are working as fast as we can, but we need help with reviewing. If you are interested in helping to review articles and giving your recommendations, please reach out to @estelaris on the #docs SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channel.

Previous articles

Props to @zzap and @atachibana for post edits.

WordPress Documentation Style Guide – Google Season of Docs 2020 Project Report

Google Season of Docs logo, WordPress logo

Google established the Season of Docs program to improve documentation for open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. projects while also enabling technical writers to acquire valuable experience with open source organizations and technical writing. My proposal for A Full and Renewed Set of Documentation Style Guide was accepted by WordPress, which was a participating organization in Google Season of Docs 2020.

Quick links:

The reason I chose this project in particular, was that this was one of the only projects in Google Season of Docs 2020 where there was a chance to implement something totally new. An extensive style guide that would govern all WordPress documentation was a testing task that I loved to take on. Additionally, out of all the projects listed on Season of Docs 2020, WordPress had the most suitable project for me in terms of technical proficiency and familiarity with the platform. From the technical aspect, I had been developing websites on WordPress for over 4 years at that time.

I had recently completed a research fellowship with a non-profit organization in open source development and administration, so I was already accustomed to an open source environment. Furthermore, the direct impact of my efforts working with WordPress Documentation were unlike any other organization. Having a direct influence in impacting millions of developers and users is what motivated me to work with WordPress for GSoD 2020.

Project description

Synopsis

WordPress is a global non-profit software organization that is dedicated to serving the global community with software that emphasizes accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility), performance, security, and ease of use. WordPress’ cause strives to democratize publishing and open source software on the web. In our digital age, a website is quite literally the online facade of an organization or individual; and WordPress serves an immense task of efficiently serving hundreds of millions of users – attributed to the 40% of the internet it runs – with their software. To further efficiently serve these users, documentation proves to be essential and is used by most developers, administrators, and end-users. Therefore, documentation can be established as a principal factor of the WordPress ecosystem. At the time, WordPress documentation didn’t include a universal and unified set of rules and style guidelines for publishing. The motive of this project was to create a full and renewed set of documentation style guidelines, universally applicable for WordPress documentation. The project idea involved consolidating all aspects of design and style guidelines like semantics, syntactics, grammar guidelines, punctuation, development-specific rules, design attributes and formatting specifics. It also incorporated language conventions like voice, tone, tense, all parts of speech, as well as naming conventions. The tools, languages and platforms used were WordPress, GitHubGitHub GitHub is a website that offers online implementation of git repositories that can 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/, Markdown, PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php., MySQLMySQL MySQL is a relational database management system. A database is a structured collection of data where content, configuration and other options are stored. https://www.mysql.com/., HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites./CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site., and JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/..

Project plan

State of WordPress Documentation Style Guides

The WordPress Documentation Team has been implementing an undeclared but unanimous methodology of publishing guidelines. But once in a while, some elements are presupposed and the process becomes speculative. There didn’t exist any fixed standard and criterion for the purpose of writing and publishing articles for WordPress. The documentation team had written project specific style guidelines, but none that were universally applicable. Most style guidelines that existed were not consolidated in one handbook, or are deprecated and need to be updated. Hence, there was a need to design and develop a unified style guide to standardize WordPress documentation. 

Objectives

Over 40% of the internet’s websites run on WordPress, which in turn indicates that millions of developers and end-users are utilizing WordPress’ impressive functionalities. Documentation is an essential element in assisting these developers and users to efficiently fulfill these functionalities without any hassles, even in case of inconveniences. The overall objective of this project was to standardize a design and style guide, unify existing style guides, and update, as well as append new regulations and specifications for WordPress documentation. This would enable ease of use, simplicity, and uniformity in WordPress documentation.

Implementation

Tools and methodologies

Before commencement of the project, my mentors and I established that a collaborative platform would be best suited to accomodate the Style Guide. Even though WordPress itself can efficiently manage editing and site administration, we chose GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/. and GitHub, as they provide a collaborative platform with a commit history and proper version control. This was especially advantageous as, with WordPress – one of the largest open source communities – come numeorus contributions and thereby various contributors, which would also make the Style Guide future-proof.

The documents were written in Markdown – of the GitHub Flavored Markdown (GFM) variety, and then were parsed by a custom parser for make.wordpress.orgWordPress.org The 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/, courtesy of @coffee2code from the MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. team.

Contributions

Leading up to the project, I had already started my contributions to WordPress well before the project commencement. I wrote, reviewed, and published various user and support articles for the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ BlockBlock Block 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 End-user (BEE) Documentation team. As a mentor for the WordPress Documentation Mentorship team, I assisted new members and contributors to get conditioned to WordPress’ work protocols and contributing guidelines. Additionally, I also participated at the Virtual Contributors Day at WCEU 2020, and contributed to the WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., Meta, and Polyglots communities.

Altogether, these interactions, involvements, and contributions proved to be beneficial for me to distinguish myself as a proficient technical writer, as well as a key contributor and team member that would efficiently complete a project.

During the doc development phase, even though there was no explicit requirement, I made an intention to consistently push commits to the repository everyday for the duration of the project – without diminishing the standard of my contributions. With the exclusion of one day, (December 1, 2020 to be exact – where I lost track of time submitting my Master’s applications :P) I achieved my intention of contributing daily.

These are my daily contributions to WordPress on GitHub (for what they’re worth).

Contributions to WordPress in 2020 by @tacitonic
Contributions to WordPress in 2021 by @tacitonic

GitHub repository for the WordPress Documentation Style Guide: https://github.com/WordPress/WordPress-Documentation-Style-Guide

This repository was specifically created for the WordPress Documentation Style Guide and my Google Season of Docs project. Accordingly, all of my commits and issues pertinent to the project can be found on the repository.

Commits authored by tacitonic: https://github.com/WordPress/WordPress-Documentation-Style-Guide/commits?author=tacitonic

Timeline and deliverables

Initially, my project was a standard-length project (3 months). 20 days into the project, I realized that there was a lot more to this project than what was my initial idea. As I researched extensively into style guides, dictionaries, and existing documentation, I came across newer topics and articles that needed to be added. Additionally, I had also been spending more time on writing every article than expected.

So, I asked my mentors whether I could extend my project duration from standard-length to long-running (5 months). They coordinated with the respective individuals and officially extended the project to a long-running one.

My main concern towards extending the project was that if the project were to be limited to the standard-length, the essential aspects of the Style Guide would have been left for some contributor after myself. I, having already researched so much into style guides, had a clear path of what else was needed. Moreover, every contributor volunteers their own time to any open source project; there’s no assurance that any individual would commit their time for an extensive project such as this one. So conclusively, I extended my project duration – giving myself more time to complete my deliverables.

Article structure of the WordPress Documentation Style Guide

Research and references

While planning as well as designing and writing, I researched existing style guides, dictionaries, and WordPress documentation extensively:

Collaboration

Mentors

Mentor: Milana Cap @milana_cap

Mentor: Felipe Elia @felipeelia

Org admin: Chloé Bringmann @cbringmann

Documentation Team Lead: Jon Ang @kenshino

Weekly meetings

Even before the community bonding phase, I participated in weekly meetings over SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. to know more about the functioning of WordPress, the Documentation team, as well as many other teams. During the doc development phase, I provided my weekly updates every Monday during the Docs team meeting. Occasionally the team would also discuss particular elements or articles in the Style Guide which were worth exchanging views about.

I would also clear up issues and difficulties during meetings; or would have them promptly cleared up in async – thanks to my mentors.

Challenges

There were a fair share of challenges that I encountered during writing the Style Guide. The first thing that I recollect thinking about challenges, is that I could not come up with relevant examples by any means whatsoever. I had my own tribulations while inventing my own examples. But once I referred to relevant documentation, existing handbooks, and support articles, I was comfortable with writing them.

What is imperative for a style guide, I had to spend plenty of time researching into what some might even consider trivial details. A great proportion of my time was dedicated towards writing accurate and unambiguous documentation.

Another challenge was related to the inherent functioning of any open source organization. Though WordPress is one of the largest open source communities, each contributor volunteers their own time to progress the project. You cannot expect and presume that someone would do a task on time as if they were employed by the organization. You have to be accomodating, and you’ll get your tasks done in good time. Regardless, WordPress’ contributors are dedicated individuals who are the benefactors of free and open source software.

Peculiar learnings

Having to build a style guide from scratch, I researched hundreds of pages in style guides, manuals, and developer documentation. Aside from researching, another huge task was to actually design and write the Style Guide. One might say that as a technical writer, you just have to formulate a plan and write documentation. But in the eight months since I started working on this project, I learned quite a lot of things in addition to writing and designing, that normally I wouldn’t have – and rather quite expeditiously.

Just to enumerate a few:

I think, in this regard, Google Season of Docs and other open source programs prove to be exceptional avenues in upskilling individuals.

Future prospects

  • Assign a permanent location for the Style Guide in WordPress docs.
  • Iron out parser inconsistencies.
  • Write the remaining articles in the word list and usage dictionary.
  • Complete internal linking and cross-referencing.
  • Review regulations that apply across all documentation.

In the immediate future, I plan to continue contributing to new projects and documentation as a team member of the WordPress Documentation Team. As I have earlier, I will also participate in and contribute to other WordPress teams such as Meta, Core, and Polyglots. I’ll continue supporting the Documentation Style Guide in my role as project committer and maintainer.

Conclusion

I sincerely hope that the Style Guide proves to be beneficial for WordPress developers and users alike. Designing and writing the Style Guide for a well-known organization such as WordPress was a unique opportunity, and I would like to thank Google for providing a program and platform for technical writers to achieve these opportunities. I was able to advance my technical writing and write over a 100 articles in a rather brief period of time. I would definitely distinguish this project as successful, and a favourable outcome for both WordPress and myself. The WordPress community has been one of the most affable and engaging communities in open source, and I look forward to a lot more persistent contributions to WordPress.

#atharva-dhekne, #documentation, #google, #google-developers, #google-season-of-docs, #google-season-of-docs-2020, #gsod, #gsod-2020, #style-guide, #tacitonic, #wordpress, #wordpress-documentation-style-guide

Requirements for a new design for the article pages in user documentation

This is post one on a four-part series. The focus on these series is the redesign of documentation that will include a new template, new categorization, new navigation and some renaming of articles. On this post, we will focus on requirements.

Some of these requirements are very straight forward, others still need a bit of discussion. The links to the PRs are included. 

List of requirements:

  1. Article voting (#7) vs feedback: contributions from the public (#240)
  2. Search area (#9)
  3. SidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. navigation styling (#111)
  4. TOC styling (see #111)
  5. Language (#201) vs localization (#283)
  6. CategoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. terms archive (#231)
  7. Mobile view (#235)
  8. Mobile sidebar (#236)
  9. WP version page (#245)
  10. Add changelog (example)
  11. Index dev notes by release (example)
  12. 404 with link to forum (#47)
  13. Icon for external links (example)
  14. Add breadcrumbs
  15. Change hovering anchor# icon

1. Article voting (#7) vs feedback: contributions from the public (#240)

The difference between “article voting” and “feedback: contributions from the public” is the type of information we gather from the user. 

Is knowing if an article is useful to a user, better than having the user’s feedback? Is there a way to merge both? Or do we want to keep them both and separate? Or would only one fulfill the documentation goals?

At the moment, there is a feedback form being tried out. The questions are: Was this article helpful? How could it be improved? The reply box is for a long comment and none of these replies/feedback is posted online.

Question is, being that the features require different information and some articles are already too long, do we need both features?

Article voting recommendation

No triggers a feedback box:

And the article will show the number of yes replies

Feedback: contributions from the public (the form that is being tested in WP.org at the moment this post was written)

2. Search area (#9)

Maintain the search area for documentation and forums. Make it prominent for mobile.

3. Sidebar navigation styling (#111)

Follow the new style for pages in WP.org. Use only the main category items on the menu with links to each subcategory TOC pages

4. TOC styling (see #111)

5. Language (#201) vs localization (#283)

Are there Rosetta sites that will not be using the HelpHub pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party to translate documentation? Is it still necessary to add the language feature? 

6. Category terms archive (#231)

This PR will be resolved with the new classification for the articles that was done via GSoD.

7. Mobile view (#235)

Currently the view on mobile for documentation uses a very large band and it gives the impression that there is nothing else. So increase information above the fold.

8. Mobile sidebar (#236)

The sidebar on the mobile version will be affected with the new navigation. At the moment, it looks like this:

9. WP version page (#245)

There will be a review but will use the same template as the documentation articles.

10. Add changelog (example)

A changelog is essential to keep users informed on what has been changed and when. It is being tested at the time this post was written.

11. Indexed dev notes by release (example)

Although the dev notes are written for developers, the docs team is interested in keeping an index page of all the dev notes written for a release. The index page will be linked from the release version page. 

12. 404-not-found with link to the forum (#47)

The new design will include a 404 page with a link to the support forums.

13. Icon for external links (example)

In the article template, include an icon to highlight a recommended site or external link. 

14. Add breadcrumbs for navigation

Breadcrumbs will be added to ease navigation

15. Change hovering anchor icon

Nowadays the hashtag # symbol has other connotations as it is common in social media. The link icon is commonly used as a hovering anchor  

This list is by far what the docs team has gathered. The post will be open for discussion and recommendations until 12 February 2021. 

The next posts on this series will be:

Part 2: Documentation: a different classification, navigation and SEO

Part 3: Draft templates for article documentation 

Part 4: Proposal for a new design for documentation 

Props @milana_cap for proofreading and final review.

HelpHub Feedback Section – new feature for contributors

At Docs team, we are putting a lot of effort into onboarding process and helping contributors to get started. One of those efforts is a “Feedback Section” for HelpHub (end user documentation).

Feedback section is resembling the User Contributed Notes section at DevHubCode Reference, so this is a comment section but with a difference of HelpHub’ Feedback Section not being publicly visible.

What is it for?

Feedback section is meant to help contributors report issues such as typos, out of date info, missing facts etc. Even though this feedback is not publicly visible, it is not anonymous. The contributor has to be logged in to send feedback. If logged out, visitor will see the message “Please log in to leave the feedback”.

Where is this feedback visible then?

This feature is enabled on HelpHub and all Rosetta sites with HelpHub enabled.

All the feedback can be found in dashboard’ comments section. It doesn’t really matter if you approve them or not so you can use this status system as a sort of tracking issues system.

We hope this will reduce the gap between new or passing by contributors and the team; and mimic the ease of contributing at Codex.

Complete discussion and the code can be found here: https://meta.trac.wordpress.org/ticket/4915

Digital Check-in for 🐝-docs team week October 19

Our Digital Check-in for this week:
Please share the following in the comments:

  • What did you work on last week?
  • What would you like to work on this week?
  • What are your blockers (things that stand in your way of your work) ?

This week is release week:

  • WordPress 5.6 BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 1 is schedule for October 20, which starts the beta/rc release testing phase. You can get a preview of the upcoming version via the WordPress Beta Tester plugin
  • GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party RCRelease Candidate A beta version of software with the potential to be a final product, which is ready to release unless significant bugs emerge. 9.2 will be published later today (Oct 19) and that is the version that will be merged into WordPress 5.6 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress..
  • Gutenberg plugin 9.2 release is scheduled for October 21.

Our reading list for this week:

Contributor Links

Looking forward to ‘seeing’ many of you at the next 🐝 docs Slack meeting on October 26, 2020 at 14:00 UTC

Exploration of a new classification for user documentation

Background

While working on a new design for HelpHub or documentation in WordPress.orgWordPress.org The 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 categoryCategory The '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 blockBlock Block 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:

A better view of the list can be found here.

Example scenario

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
  • Managing Plugins

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
  • phpMyAdmin
  • Creating a Static Front PageStatic Front Page A 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
  • Update Services
  • Settings Writing Screen
  • Administration Screens
  • Giving WordPress Its Own Directory
  • Settings Reading Screen
  • Dashboard Screen

What it is like on mobile

On mobile, the situation is the same. 

Looking into the future

Target audience

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.
  • Others?

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:

  • WP basics – overview, features, history, glossary, semantics, contributing.
  • Technical documentation: installation guides, requirements, best practices, technical how-to, security, troubleshooting.
  • Support documentation – dashboard structure, user permissions, screens, media screens.
  • Project related documentation – customization, themes & plugins, design how-to’s (blocks)

Relation to time and development

There are articles that have been superseded by new development and are either no longer relevant to the software itself or must be updated. We need to include 4 buckets where we should add articles:

  • No longer relevant or valid
  • Need update
  • Convert from Codex as is
  • Create new documentation

Next Steps? 

The docs team will continue working on defining the user personas, as well as the information pillars.

We plan on having a proposal on documentation structure that includes clear navigation and new classification, by the end of the summer.

If you would like to contribute to the project, leave your comments. Comments will be discussed during the #docs team meetings on Mondays at 15:00 UTC

Summary for Docs Team Meeting: 09 March Meeting

The agenda for this meeting is on the https://make.wordpress.org/docs/2020/03/09/agenda-for-docs-team-meeting-9-march-2020/.

Attendance

@Kenshino (Jon), @cristiano.zanca, @milana_cap, @atachibana, @pmbaldha, @tomf, @bph, @leogermani, @nullbyte, @themiked, @johnbillion, @felipeelia, @chetan200891, @yui, @pbrocks

Documentation License for HelpHub, DevHub

@kenshino (Jon) have chatted with Matt Mullenweg and he is okay for multi-license setup with a specific reason as long as GPLv2 is the default for all documentation across the WordPress project.

CCO provides a more open domain in comparison to GPLGPL GPL is an acronym for GNU Public License. It is the standard license WordPress uses for Open Source licensing https://wordpress.org/about/license/. The GPL is a ‘copyleft’ license https://www.gnu.org/licenses/copyleft.en.html. This means that derivative work can only be distributed under the same license terms. This is in distinction to permissive free software licenses, of which the BSD license and the MIT License are widely used examples.. The GPL isn’t necessarily the best for the documentation but it isn’t really explored how that manifests in real-life usage.

Documentation Team members should decide which license will be used. @milana_cap will write the post in p2 for license feedback. @kadamwhite had replied that he was comfortable with GPL for the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. handbook, but The CLICLI Command Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress. handbook is licensed under the MIT.

@Kenshino (Jon) strongly recommends each representative for projects in Docs to chime in Theme Handbook, PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party Handbook, WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ Handbook etc.

Once the documentation team decides then the documentation team members need to place license info into each logical division of our documentation.

Project Updates 

@milana_cap had written the documentation team profile badge page https://make.wordpress.org/docs/handbook/get-involved/documentation-team-profile-badge/.

As per the @themiked@garrett-eclipse had given some updates for the privacy bits for the plugin handbook but no changes made until now.

Moreover, @themiked has said that the wpdb documentation page is done but the PR to update the inline docs in code (https://core.trac.wordpress.org/ticket/49477) isn’t done yet.

@stevenlinx and @atachibana are working on setting a re-routing codex page. According to the @atachibana, 397 of 1069 (37.1%) code reference for functions pages have been rerouted.

According to the @leogermani, 13 hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. have been migrated out of 255 (3.7%) from codex page to the Devhub. It’s really easy task. If anyone wants to help and don’t know how, please pingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” to the @leogermani. @nullbyte was ready to contribute to it.

Policy for external linking

It is a very controversial topic. Few members are in favor to put external links and Other few members aren’t in favor of it.

@milana_cap proposed to allow external links by people who are active in wordpress.orgWordPress.org The 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/ team members (no companies) in that specific topic.

@bph said that WP docs should be self-contained.

External links are outdated by time. To monitor them time by time is vast task for documentation team.

@milana_cap will write this up into a coherent P2P2 P2 or O2 is the term people use to refer to the Make WordPress blog. It can be found at https://make.wordpress.org/. post and outline the possible routes the documentation team can go.

Workflow for content change approval

All team members are agree with below workflow which has proposed by the @Kenshino (Jon):

  1. Any documentation project member should be able to ask the project rep for review
  2. Any project rep change (not #1 but their own change) – some other project rep or @Kenshino (Jon) can be the second pair of eyes
  3. Tiny grammatical / screenshot changes need not go through this approval process

The workflow will be tracked by appropriate and transparent communications in #docs.

Open Floor

All project representatives should read the Badge policy that @milana_cap wrote on the https://make.wordpress.org/docs/handbook/get-involved/documentation-team-profile-badge/. @Kenshino (Jon) want to get a consensus in the next meeting.

@tomf will facilitate next meeting.

@leogermani said that the i18n section of the plugin handbook is one is very outdated. @themiked will add it to his whiteboard list. There is a need to redirect the localization/internationalization pieces to the Common APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. handbook. It isn’t unique to plugins or themes. The Plugins handbook needs a deeper refactoring.

#documentation-license, #external-linking, #meetings

Findings in the reclassification of WordPress.org documentation

One of the goals for the redesign of the documentation in WordPress.orgWordPress.org The 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/ is to create a better search. The best way to do it is by reclassifying all the articles and creating categories with subcategories.

In discussions with the #docs team, we agreed that the best option to do this was by working with a group of people that included developers, documentation, designers and content specialists.

Our goals for the working session were:

  • Classify documentation articles in categories and provide subcategories if possible
  • Utilize the already existent categories and perhaps add one or two. The reasoning is that we already have many users that are familiar with it.
  • Think of the final user: new user to advanced user, not necessarily advanced developers  

A working session during Contributors Days at WordCamp Vienna with about 15 contributors gave us some ideas. The results show the following recommendations:

  1. Some articles need a more descriptive title
  2. There are still articles that do not have updated information
  3. Articles should be placed in one categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging./subcategory, even if the information could be related to other categories
  4. There are unnecessary articles that must be removed. An example of this is the article WordPress Lessons that only offers links to other articles. Once the reclassification is done, there won’t be a need for this type of articles
  5. Revisiting 170+ articles is going to take a lot of time. Some participants from WC Vienna agreed on continuing reading the articles but we will need more people

We are looking for volunteers that would like to help us with the classification and or would like to add a working session during contributor dayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/. at WordCamps.

Summary for Docs Team Meeting 9 December 2019

Transcript: https://wordpress.slack.com/archives/C02RP4WU5/p1575903630148600

Facilitator and Attendance

Facilitator: @kenshino
Note-taker: @ibdz

@kulsumsiddique will be facilitating next week’s meeting.

Attendees: @kenshino, @FahimMurshed, @atachibana, @ibdz, @kulsumsiddique, @mukesh27, @ediamin, @fierevere, @Carike, @nullbyte, @bph, @udfibonacci, @felipeelia, @estelaris, @leogermani

HelpHub Updates

@atachibana reported that there are no any movements for HelpHub except new release notes such as 5.3. The team is working on some page of GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ User Guide that was missing.

@kenshino started an idea to do a survey to find out the completeness and quality of end-user documentation. The survey is targeted to go out by February 2020. @atachibana and @bph will help create a survey about all end-user documentation.

HelpHub Localisation

@atachibana updated that there were 30 Japanese Codex pages migrated to Japanese HelpHub on the Contributor DayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/. at WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. Osaka.

Common APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. Handbook

@leogermani fixed some error on i18n page and has been working on editing plugins and themes handbooks.

DevHub Updates

@atachibana reported: Content: 280 of 1069 (26.2%) pages were redirected. Last week was 264 of 1069 (24.7%).

Next week meeting focus

@kenshino suggested about next meeting focus on discussing the Docs team organisation generally which could include Badges, Handbook, Management, or Meetings.

@kenshino asked all contributors who’d like to join Docs team regularly to give feedback to this post (https://make.wordpress.org/docs/2019/12/08/trac-trello-discussion-the-way-to-report-and-discuss-documentation-issues/) before next meeting.

Open Floor

Trac/Trello Discussion – The way to report and discuss documentation issues

This discussion started in Slack during one of Docs team meetings. It was discussion about the best tool for tracking progress and issues for blockBlock Block 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 end user documentation. However, the question of tool is widely applicable to all Docs projects, hence the need for this post and discussion.

Having complete documentation on Codex made contributing to Docs team easy in a way that everyone, as long as logged in, could modify existing or add completely new parts of it. However, this method had its flaws. It was impossible to track which parts of documentation were modified. And if we can’t track modifications then we can’t check the correctness of newly added information as well as the quality of code examples.

It took few years but we moved big parts of Codex to new places, built on WordPress. While we have more control as complete content goes under our review, this move made contributions to documentation team fairly difficult. The process itself is unclear, different Docs team’s projects use different tools (none of which covers all we need) but the common scenario we end up with is people reporting issues in SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. #docs channel.

The Tools

Documentation team uses several tools in contributing process. We have several Trello boards with more or less activity. Also, progress for almost all projects is tracked in Google Docs.

HelpHub content is tracked in Google Drive while development uses GitHub repository for development and Meta Trac for production issues.

Contributing to code reference can be done with code examples through User Contributed Notes (e.g. User Contributed Notes for activate_plugin() function) or with inline documentation via Core Trac (which is more CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. than Docs team’s responsibility).

Plugin developer handbook gets updated when someone reports issue in Slack channel while Theme developer handbook used to use Trello board but we handed over leadership to Theme Review Team (even though Docs team is still helping when needed).

Common APIs handbook uses Google Spreadsheet.

Block editor uses Trello board and Google docs for end user documentation and GitHub for developer’s documentation.

We also have Documentation Trac available. It hasn’t been used for anything before.

What is the problem?

Different projects have different workflows and, therefore, different tools. However, we have several problems to solve:

  • Access – while we do welcome everyone to contribute to Docs team, we also need to be careful with giving access to handbooks hosted at wp.org. If we want to make sure that only curated info gets into handbooks we need to limit access. That also means that whole burden of reviewing and maintaining handbooks falls on these few people who have access.
  • Keeping track of contributions and contributors – the easiest way to keep track of contributions/contributors is to use tools we have available at wp.org (TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. and Slack). On the other hand, Trac is not the most intuitive tool for wider range of WordPress users and Slack tends to burry information so the history is lost in tons of archives. Also, in some cases it is important that we have a history of a decision/discussion available at one, easy to access, place.
  • Project managing – each project is different but it is a project nevertheless. It is important that the tool we use for it have project managing features which will make contributing to the project easier (joyful is preferable).
  • Onboarding and taking over – Onboarding is huge problem of every open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. project and it’s naive to think we can solve it with one tool. But also, it’s not just to tool we need to onboard people in, it’s the workflow as well. The tool we chose and the way we use it should be intuitive enough not to stand on our way to contribute and not to make project depended on a specific person. Most of this could be solved with a detailed documentation on the workflow itself.
  • There could be more, leave your thoughts in comments.

What are we deciding here?

We are not trying to decide on one tool over the other. We are trying to discuss all the tools we already use, how they solve our problems and how they help our workflow.

Most importantly, we want to figure out the way for reporting and discussing Docs issues. Preferably, we would come up with a unique way for all docs projects but given the differences between projects, it wouldn’t be considered as a failure if we don’t.

However, it is important that we come up with a way to report and discuss issues for each project. Results of this discussion will end up in our Handbook as a reference for contributing to Documentation team.

Please, leave your thoughts in comments.