What to do with old/obsolete documentation

While recently reviewing the content of the plugins handbook, I discovered some content that is no longer current (specifically, this page that deals with the term splitting fix that happened four years ago as part of the automatic upgrade process for 4.2).

After some discussion with the documentation team it became clear we lack a unified way to identify which documentation is obsolete, and what to do about it when it is. As a result, old docs end up hanging around in a position of implied accuracy, potentially adding to confusion.

To begin with, we need to answer these questions:

  1. What is considered obsolete? Is it even possible to come up with a general rule for this?
  2. Who decides if a page is obsolete?
  3. What do we do about it? (see below)

Once the obsolete docs are identified, we need to decide what to do with them:

A. Do nothing (this is here for completeness’ sake. This is not a valid path forward.)
B. Delete them
C. Leave them in place and mark them as obsolete as of a specific WP version or date
D. Move them to an “archive” or “legacy” section and mark them as obsolete as of a specific WP version

Depending on the decision this will require some or all of the following:

a. standardized markup to appear at the top of a page, to clearly identify that this entire page is considered legacy (hopefully via a shortcodeShortcode A shortcode is a placeholder used within a WordPress post, page, or widget to insert a form or function generated by a plugin in a specific location on your site.)
b. standardized markup to clearly identify a specific section of a page that is is considered legacy
c. a place in each handbook for legacy documents, along with markup to clearly identify them as such

I suggest the following

  1. The identification of a page or page partial that should be discussed can be put forward by anyone
  2. The “owner” of the handbook (or whatever) along with anyone else of interest can discuss the validity of the content in question and determine if it should be adjusted.
  3. If it has been determined that the content is no longer relevant, the correct action (one of B. C. or D.) can take place.

I realize this may seem like navel gazing but if we can at least come up with a general consensus on how to handle this situation, it will provide a starting point.

External Linking Policy – 1st review of Plugin Developer Handbook

As the title suggests, this is a first review, using the Plugin Handbook as the testing documentation. We will conduct this initial process to work out the External Linking Policy, which is currently still in “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.” phase. Over time, the policy will evolve and take shape as we better understand what it should cover.

The Goal

The goal of this first review has several points:

  1. Classify all external links found in the Handbook;
  2. Define “undoubtedly allowed” links;
    • Propose a list of “undoubtedly allowed” links;
  3. Define “pre-allowed” links;
    • Propose a list of possibly “pre-allowed” authors and websites;
  4. Propose phases of the acceptance process and draft their definitions;
  5. Start discussion about pre-allowed list and acceptance process phases;
  6. Draft a timeline of actions for next steps;
  7. Select at least 3 Docs team members who will act as “official reviewers” for this first review.

All external links found in the 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 can be found in Docs team’s Google Drive document (with occasional comments from the first review performed by myself): https://docs.google.com/spreadsheets/d/1GhFv8p9veimVM3jMhhazttJLunRjcW7pg0-WO5E0NRk/edit?usp=sharing

1. Classify all external links found in the Handbook

While performing my first review, I classified all resources into “Personal authors” and “Non-personal domains”. This is a very rough classification based on one single difference. 

A person can publish content on different websites and therefore can come out as authors on different resources of which some may meet our policy and some may not (e.g. promo article for a plugin/theme/service). On the other hand, if said person’s content, published on 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/, gets accepted, it doesn’t mean we will accept all resources hosted at github.com.

Non-personal domains with a single author represent one set of rules/values/niche etc and therefore come out as a singular resource that won’t publish content at different domains. Non-personal domains with multiple authors, such as GitHub, YouTube, npmjs etc, can not be seen in this case as a single resource but rather as a tool where different persons publish their content. Seeing GitHub as a singular resource would make sense only if we would consider for example their official blog.

2. Define “undoubtedly allowed” links

What does “undoubtedly allowed” mean?

“Undoubtedly allowed” refers to official or authoritative resources for their respective topics. They go in depth with their topics, and we can expect them to be the most up-to-date resource on that topic. Examples include php.net, gnu.org

2a Define links that can stay and be “undoubtedly allowed”.

Out of all links found in Plugins Handbook, this is my proposed list for “undoubtedly allowed” domains: 

Please note that this list is made up of links actually found in the Plugins Handbook; we don’t need suggestions for random sites not currently in the docs. Please feel free to post your own list in the comments below, once you make sure that your proposed addition actually exists in the Plugin Handbook (provide a link please).

3. What does “pre-allowed” mean?

“Pre-allowed” means that we know this person or website has been giving sound advice and has been nurturing WordPress’s values and principles in the past. Therefore, we have a reason to believe this practice will continue in the future. It does NOT mean that this content will be exempt from review for its relevance and up to date information. 

Links in this classification will not go through the whole “acceptance process,” but rather a content check: 

  • Is it relevant for the part of documentation where it is proposed?
  • Is the information up to date?
  • Is the content in whole meeting External Linking Policy requirements (e.g. not recommending specific plugins/themes/services)?

3a. Propose a list of possibly pre-allowed authors and websites.

Please go through the list in this document and post your “pre-allowed” proposal in comments below. If you feel you should explain your choice, please do. 

This will help us understand values and holes people see in WordPress Documentation and will be a huge starting advantage once we move into the next phases of this policy.

4. Propose phases of the acceptance process and draft their definitions.

In the aforementioned document I have created a “Status (Acceptance phase)” column to indicate the phase in which each link is currently classified. The list of phases will directly affect the whole review workflow so it is reasonable to expect this to change and the workflow to be refined in the future.

Some phases we can be sure to keep all the way, obviously. Such as:

  • Reviewing
  • Accepted
  • Rejected

However, “Reviewing” is rather broad and vague. This phase could be expanded further to, perhaps:

  • Reviewing – Relevance
  • Reviewing – Updated info
  • Reviewing – Advertisement
  • Reviewing – Free access (no paywalls etc)
  • Reviewing – Website/webpage (upholding WordPress values etc)

Broken into smaller phases, the Review phase can be performed easier while the whole process gains clarity and transparency.

If you have any suggestions for phases of the acceptance process, please post them in comments below.

5. Start discussion about pre-allowed list and acceptance process phases.

Hopefully, the comments section will be sufficient for a constructive and productive discussion. If not, we can organise another conference call meeting and clarify all that is indistinct and vague. 

6. Draft a timeline of actions for next steps.

The ultimate goal for Plugin Handbook, as the guinea pig for this process, is to clean up all existing external links, remove invalid ones and (if necessary) restore any valid ones (both, personal and non-personal). 

During this process, we hope to define a pretty solid policy that works in the best interest of Documentation consumers.

To draft a timeline of actions for documentation where we already have external links, first we need the actions defined. While working on this initiative and thinking about possible scenarios, personally I can identify few steps:

  1. Define and apply “undoubtedly allowed” links. Document the process along the way.
  2. Define and apply “pre-allowed” personal and non-personal resources. Document the process along the way.
  3. Review the rest of the links, remove unfitted and keep fitted ones. Document the process along the way.

It’s hard to estimate a process that we have never done before (even the ones we have) but we do need some time frame to make sure this project doesn’t end up unfinished. 

By rough estimation, I’d say that this process could last 6 months in total. First step should be the shortest: ~ 1 month, the last one looks like the longest so I’d give it 3 months which leaves us with 2 months for the second one. As we have already stepped into the first one, the timeline could then look like this:

  1. “Undoubtedly allowed” phase finished by the end of 2020.
  2. “Pre-allowed” phase finished by the end of February 2021.
  3. “The rest” phase finished by the end of May 2021.

If we completed everything within this timeline, 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. Europe 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/. could be a good moment to start work on other parts of Documentation.

7. Select at least 3 Docs team members who will act as “official reviewers” for this first review.

These 3 Docs team members will be noted as a committee who approved “undoubtedly allowed” links. Of course, the more people conduct review and share feedback – the better, but we need defined names responsible for allowing/rejecting resources to make sure reviews will be conducted in full and taken seriously.

Obviously, I already did the first review, so I need two more volunteers who are members of the team and familiar with this whole initiative.

If you are interested, please post it in the comments below.

#external-linking-policy

Follow up on Gutenberg developer documentation restructuring proposal

The proposal to restructure 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/’s developer documentation was discussed a few weeks ago during the weekly 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/. office hours (rollback to the discussion here, meeting notes here).

We agreed that it makes sense to clearly identify stakeholders and use cases of the documentation before any action is taken.

This information has been collected in this Google Docs document.

The main stakeholders identified are:

  • Site developers: people who create WordPress sites with custom themes and plugins.
  • Site builders: people who create sites with primarily a page builder, or a theme that includes a page builder.
  • Theme Authors: Developers of WordPress themes, hosted on the official theme directory or elsewhere.
  • 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 authors: WordPress plugin developers.
  • WordPress Core contributorsCore Contributors Core contributors are those who have worked on a release of WordPress, by creating the functions or finding and patching bugs. These contributions are done through Trac. https://core.trac.wordpress.org.: People who contribute to the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. of WordPress, to Gutenberg, etc…
  • Content creators: People who create content on WordPress sites.

For each of these stakeholders, the nature of the expectations are different. Theme developers or contributors to WordPress want to be able to alter the way 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 works, its structure or presentation; while site builders and content creators expectations will be best met by the user documentation for the block editor.

Next Steps

The major use cases that emerge from all those in the document mentioned above are:

  • Update/alter the UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. or the structure of the editor and its elements
  • Create blocks for the block editor
  • Create block patterns
  • Programmatically modify or trigger the functioning of the block editor and its elements

The next steps to move forward could be to propose a structure around these major use cases.

You can do this as a comment to this article. This will also be on the agenda for the next JavaScript office hours.

#block-editor, #developer-documentation

Gutenberg developer documentation – Zoom meeting agenda

In a previous post, we shared a Doodle link to choose times to attend a Zoom meeting on 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/ developer documentation.

The selected date for the meeting is:

Wednesday, December 02, 2020, 08:00 UTC

Zoom link: https://us04web.zoom.us/j/79656401480?pwd=cXZ1U2t2MjFYQUFrQ3EwMzRLYW93UT09

Topic: WordPress Documentation Team - Gutenberg Developer Documentation

Join Zoom meeting:
https://us04web.zoom.us/j/79656401480?pwd=cXZ1U2t2MjFYQUFrQ3EwMzRLYW93UT09

Meeting ID : 796 5640 1480
Passcode : 9xHGhA

If you want to participate in the meeting, please read the initial restructuring proposal and the follow up post if you need more context.

Agenda

  • Introduction to the Gutenberg developer documentation restructuring proposal
  • Review of the current structure of the documentation (@paaljoachim)
  • Review of documentation use cases
  • Discussion on adjustments to be made to the documentation and next steps to move the project forward
  • Open floor

If you have others items that you would like to be discussed at the meeting, please comment on them in this post.

#block-editor, #developer-documentation

Agenda for Docs Team Meeting November 30, 2020

The next meeting is scheduled with the following details:

When: Monday, November 30, 2020, 15:00 UTC

Where: #docs channel on Slack.

Meeting Agenda

  1. Project Updates
  2. New Member Mentoring
  3. Monthly Coffee Break
  4. Meeting Times
  5. 2020 Holiday Planning for Docs Team
  6. Google Season of Docs 2020
  7. Discussion: Structure of the Handbooks using flow chart
  8. Open Floor

#agenda, #meetings

Doodle for best Docs Team meeting time

Hello all,

I’d love for everyone to fill in their preference for a good meeting time. We’ve been struggling with new schedules, DST and the likes.

I’ve deliberately kept it at Monday and simply extended the possible overlap period that might give a chance for EMEA, APAC and US to meet.

We might in the future split to 2 calls but I’m hoping to start that discussion when we’re through the COVID period and people are maybe returning to offices which affects their schedule.

The doodle is here https://doodle.com/poll/it4m9bf24q92she6

I’m also aware there was an earlier doodle and would like to apologise, it wasn’t clear to us if people voted with their local time in mind or made conversions with UTC.

This doodle comes with local timing – (you can change it of course) so please vote. I’ll tally before our next meeting on 23 Nov and ratify the new meeting timing then!

Summary for Docs Team Meeting on 09 November 2020

Attendance

@crs1138, @chaion07, @leogermani, @atachibana, @tacitonic, @stefanocassone, @justinahinon, @veralee, @crstauf, @kafleg, @harishanker, @FahimMurshed, @sukafia, @mehbubrashid, @estelaris, @kenshino

Thanks to @leogermani for facilitating the meeting.

Housekeeping
Project Updates

MigrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. from Codex to Code Reference: @stevenlinkx and @collinsmbaka continued migrating and re-routing Codex to Code Reference: 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. 124 of 355 (34.9% < – 30.4%). @atachibana edited each method of information of the class references. @dd32 added a redirect to every page. No change in 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 until the external linking and the obsolete docs gets resolved.

Meeting Times

Due to the general confusion with the time-zones on the current Doodle, @kenshino will create a new Doodle and @crs1138 will notify all contributors who already voted on the original Doodle about the need to vote again.

New Member Mentoring

There are 5 new members joining #docs in the week between 2 and 9 November 2020.

Monthly coffee break (November 2020)

@estelaris will run the next monthly coffee break which will be on the Thursday 19 November 2020. The time for the coffee break should be Asia friendly and will be specified later on.

Google Season of Docs 2020

@tacitonic is currently working on the Punctuation section and updates the progress in the README file on the daily bases.

@dmivelli has finished reviewing the discoverability project and submitted a long list of typos and grammar errors that @estelaris will be fixing this week. There are also many titles that must be changed.

Docs Handbook and facilitating collaboration

@leogermani and @themiked rewrote a couple of pages but there is still more work to be done. As an example @leogermani pointed out the Projects page that could reflect more precisely what’s going on in their team. They also worked on the Workflow page. @leogermani suggests an idea to add a “report an issue” button to the pages to make it easier for people who want to collaborate to find their way.

@estelaris confirmed that this kind of button will be part of the new design of the articles template.

@themiked will add a link to the Reporting an issue page to the bottom of every plugin handbook page.

Deprecated Links

@themiked wrote down a document regarding the deprecated links and is asking for some feedback.

#meeting-notes, #meetings, #summary

Docs Team Coffee Break November Update!

Hello Folks,

As we inch closer to a second wave of COVID, it has become more important than ever to stand next to our fellow contributors. The idea of having a monthly informal discussion in the form of a ‘Virtual Coffee Break’ experience is something we are finding rather helpful while trying to maintain proper social distancing. Even though we would hope for majority of our fellow contributors to join in and support the same concept it may not always be the case. Understanding this, the team came up with the idea of rotation in the timing to serve multiple time zones. Additionally, we expect to write a dedicated p2 post with the information covering the Docs Team Coffee Break.

October Coffee Break Summary

Coffee Break began with a smile!

The October Coffee Break took place on the 29th instant with a EU-friendly timing which saw the presence of 7 contributors from the Global Documentation Team. Kudos to @sukafia for facilitating it. @chaion07 @crs1138, @tacitonic & @thisisyeasin were among the ones who joined in.

November Coffee Break Reminder

The next Coffee Break for Docs Team is scheduled for 19 November, Thursday at 10 AM UTC. @estelaris will be facilitating this month’s Coffee Break. The details for joining the Zoom call are as follows:

The details will also be posted in #docs channel on the day. If you wish to get a calendar invite then 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.” @estelaris, @sukafia or @chaion07.

#coffee-break, #meeting

Summary for Docs Team Meeting on 02 November 2020

Attendance

@chaion07 @atachibana @veralee @softservenet @harishanker @leogermani @kafleg @hellofromtonya @FahimMurshed @crstauf @kenshino @tacitonic @estelaris

Thanks to @chaion07 for facilitating the meeting.

Housekeeping
Project Updates

@bph posted an update asynchronous to the meeting.

  • The team will be working on the “Sprint for BEE-docs” during November 25 – 27, 2020. Details will follow. If interested, please leave a comment on the digital check-in post.

@atachibana informed about adding dropped information of Codex to code Reference and re-routing:

  • 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.: 108 of 355 (30.4% < – 25.4%)
  • He also spoke on editing method information of each class’ references.
  • He also thanked @stevenlinx and @collinsmbaka for their contribution. 

@milana_cap previously published a p2 post on HelpHub.

Meeting Times

The team is still awaiting responses to the Doodle link from everyone for the meeting time as many parts of the world have already begun adjusting to the Daylight Saving Times. Please cast your preferences using the Doodle link.

New Member Mentoring

@tacitonic informed the team that we didn’t have any new member joining #docs this week.

Monthly Coffee Break

7 people joined in the Monthly Coffee Break for October 2020 with an EU-friendly timing. A few snaps from the meeting were shared with the team. Thanks to @sukafia for facilitating it including @tacitonic, @crs1138, @chaion07, @thisisyeasin and others who joined.

The next Coffee Break will take place on the 26th of November (tentative). More info will be shared as we draw closer to the date. 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.” @sukafia or @chaion07 if you require further assistance.

Google Season of Docs

@tacitonic & @diana did not have anything new to add for this week.

@estelaris suggested that a meeting is scheduled for everyone involved in the GSoD project to take part in.

Open Floor

@joyously brought up this question, a few weeks ago: What to do with articles/pages that contain information that is no longer relevant or deprecated

@leogermani suggested adding a deprecation notice at the top of the page and link to relevant up to date content.

@themiked will write a p2 post covering different aspects of the topic discussed.

#meeting-notes, #meetings, #summary

Summary for Docs Team Meeting on 16 November 2020

Attendance

@chaion07 @kenshino @tomford @collinsmbaka @leogermani @obt28 @tacitonic @mkaz @atachibana @FahimMurshed @Veralee @hellofromtonya @justinahinon @estelaris @themiked @paaljoachim

Housekeeping

Agenda: https://make.wordpress.org/docs/2020/11/16/agenda-for-docs-team-meeting-november-16-2020
Notetaker: @justinahinon
Next Meeting: 23 November 2020
Find the meeting transcript here

Project updates

@atachibana gave an update of the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. and re-routing of Codex to Code Reference:

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.: 153 of 355 (43.1% < – 33.8%). They’re also editing each method information of class references.

@bph mentionned prior to the meeting they’ll post asynchronously a digital check-in for the documentation team.

@justinahinon posted a follow up 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/ developer documentation restructuring proposal.

Meeting times

@kenshino mentionned the Doodle for the documentation team meeting time. Please fill it if you haven’t yet.

New Member Mentoring

There were no update for this item.

Coffee Break November

The next coffee break will take place on the 19th of this month at 10am UTC. Here is the link if you want to add it to your calendar: https://us02web.zoom.us/j/83074914582?pwd=RlJkMkdnbzdKODZYbENzeUpXWGF2QT09.

If you want a Google Invite for the coffee break, you can also send a private message to @estelaris on 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/..

You can also find all the details in this 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: https://make.wordpress.org/docs/2020/11/16/docs-team-coffee-break-november-update.

Google Season of Docs 2020

@tacitonic made some updates about the progress on this project:

On the reclassification front, the team is still reviewing articles for content errors but have already finalized the title change. More details are in this spreadsheet: https://docs.google.com/spreadsheets/d/1_Ea2yeF5Rfy_YDk7pBRJ4rdljhMjygXFqBq8gWwhbaE/edit?usp=sharing.

The team also discussed the big problems with titles which is the use of gerunds (words ending in ‘ing, as in working, reading, etc). This discussion can be found here.

Docs Handbook and facilitating collaboration

@themiked shared last week some updates on legacy docs which @kenshino is reviewing.

@paaljoachim asked if there have been any talks about refreshing the design. As using bigger fonts gives more space and better readability.

#meeting-notes, #meetings, #summary