Wayback Machine
«FEB MAR APR »
Previous capture 30 Next capture
2019 2020 2021 »
0 captures
1 Nov 19 - 28 Feb 22
Close Minimize Help
Skip to toolbar

WordPress.org

Welcome to the official home of the WordPress documentation team.

This team is responsible for coordinating all documentation initiatives around WordPress, including the Codex (moving to HelpHub and DevHub), handbooks, parts of developer.wordpress.org, admin help, inline docs, and other general wordsmithing across the WordPress project.

Want to get involved?

There are many ways in which you can help the Docs team. Every small contribution counts and helps! You can report an issue or typo you found in the docs, or even help us write new documentation for parts that are still missing. These are some helpful links to find out more about what we do and how to collaborate:

Weekly Meetings

Join our discussions of documentation issues here on the blog and on Slack.

The documentation team holds bi-weekly office hours on Mondays from 15:00-16:00 UTC in the #docs Slack channel.

Although we have a fixed schedule of weekly meetings, you can contact the Docs Team at any time through our Slack channel.

Make WordPress Documentation

Keyboard Shortcuts | Hide comment threads

Changing the nature of our weekly meetings

So HelpHub has already been deployed and other projects are in need of some focus.

I’ve been thinking about how to make our meetings more useful. Meetings that are just about updates aren’t the best use of everyone’s volunteer time.

Meetings that require involvement but no one is prepared for ain’t the best either.

So I’m hoping that we can improve how we run the meetings. I’d love for everyone to suggest something.

I’ll start off –

  1. Let’s rotate facilitators and note takers. Both roles have the ability to help someone really get into the groove and understand the Docs Team.
  2. Let’s change all meetings to Docs Team meeting (no special HelpHub dedicated only meetings)
  3. Let’s time-box each section of the meeting
  4. Let’s have focuses for each meeting. (e.g.)
    • Docs Team Meeting (60% time on HelpHub discussions, 40% other pieces)
    • Docs Team Meeting (60% time Docs Handbook, 40% other pieces)
    • Docs Team Meeting (60% DevHub discussions, 40% other pieces)
    • Docs Team Meeting (60% Flagship WordCamp contributor day discussions, 40% other pieces)
    • You get the drift!

Any better ideas? I’d love to hear them!

Agenda for Docs Team Meeting 30th March 2020

Our next Documentation Team meeting is scheduled for Monday, March 30, 2020 at 03:00 PM UTC

in the #docs channel on Slack.

Items to discuss:

  1. Attendance
  2. Notetaker & Facilitator selection
  3. Project Updates
  4. Handbook revamp
    • Homepage update
    • Deadline for next 2 or 3 pages
  5. Categorization Project, Alterations Workflow (discussion)
  6. Open Floor

#agenda, #meetings

Summary for Docs Team Meeting 23rd March 2020

Attendance

Facilitator: @estelaris
Notetaker: @sukafia

@estelaris, @kenshino, @leogermani, @WPZA, @bph, @nao, @atachibana, @estelaris, @tomf, @pbrocks @sukafia, @nobnob, @audrasjb @zzap, @netpassprodsr, @FahimMurshed, @marcio-zebedeu, @joyously, @ibdz

Facilitator next week: @sukafia
Next meeting will hold on:

Monday, March 16, 2020 at 03:00 PM UTC

Project updates

@bph updated the WordPress editor article and hopes to do two/three of the missing pages a week on the end-user documentation for the block editor.

@atachibana re-routed Codex Function pages to Code Reference. Completed 39% (417 of 1069).

@estelaris commended @bph for the update on the WordPress editor and asked if there were still missing articles for the block editor, which @bph responded that a few pages were missing among the embed blocks and the new blocks in 5.3 and 5.4. and some are in dire need to updates as the UI changed a bit, but that’s a bit of an uphill battle as they UI will change again in August.

@bph shared the Trello board for Gutenberg end-user documentation. – http://wayback.fauppsala.se:80/wayback/20200330064509/https://trello.com/b/JnTCzOsL/gutenberg-end-user-docs

@Marcio-zebedeu offered to help in Migrating Code Reference. @estelaris prompted everyone who’s volunteering to help someone to please specify the project/task so we can properly record it in our notes.

Handbook revamps

@estelaris made it known that @leogermani wasn’t available in the meeting due to meeting conflicts but that he will consolidate the changes to our welcome box later in the day and publish it.

Categorization project

On the categorization project, @estelaris said we “must find high-level goals and create user stories to exemplify our goals and to give better direction to those that would like to help and are outside the docs team” She shared a link to the spreadsheet for the project – http://wayback.fauppsala.se:80/wayback/20200330064509/https://docs.google.com/spreadsheets/d/1_Ea2yeF5Rfy_YDk7pBRJ4rdljhMjygXFqBq8gWwhbaE/edit#gid=1762929540

@estelaris briefed the team that “there are exactly 172 articles that we need to reclassify and that a group of contributors at WordCamp Vienna had helped to create categories and subcategories that could help but that they’re still far from finishing the project. She added that the new categories/subcategories are on the “Category Recs tab”.

Several deliberations were made on this. It was agreed that articles shouldn’t be repeated, tags were suggested as a way to co-relate articles.

The conclusion was to decide on goals and come up with user stories next time.

Open floor

@netpassprodsr volunteered to contribute to Re-routing of Codex Function pages to Code Reference.

@sukafia shared a draft of the “Extending WordPress” article which he had suggested to be included in the documentation in the previous meeting. He’s to work on it alongside @tomf for inclusion in the Overview of WordPress article.
http://wayback.fauppsala.se:80/wayback/20200330064509/https://docs.google.com/document/d/11fPqjpFNDQt0WKtnTkk_VAnUMYMndoEd9ppGZf1mcBw/edit

Transcript of the meeting:
http://wayback.fauppsala.se:80/wayback/20200330064509/https://wordpress.slack.com/archives/C02RP4WU5/p1584975640002300

#meetings, #summary

Agenda for Docs Team Meeting 23rd March 2020

Our next Documentation Team meeting is scheduled on Monday, March 23, 2020, 04:00 PM GMT+1

in the #docs channel on Slack.

Items to discuss:

  1. Attendance
  2. Notetaker & Facilitator selection
  3. Project Updates
  4. Handbook revamp
    • Welcome Box update
    • Homepage update
    • Deadline for next 2 or 3 pages
  5. Categorization Project, Alterations Workflow (discussion)
    • Finding high-level goals
    • Creating user stories
  6. Open Floor

#agenda

Summary for Documentation Team Meeting 16 March, 2020

Attendance

@softservenet, @kenshino, @milana_cap, @pbrocks, @ataurr, @felipeloureirosantos, @pmbaldha, @atachibana, @kartiks16, @passoniate, @tjnowell, @marcio-zebedeu, @estelaris, @deadpool76, @sukafia, @cristianozanca, @leogermani

Notetaker: @milana_cap

Facilitator next week: @estelaris

Next meeting will happen on

Monday, March 23, 2020 at 03:00 PM UTC

Project Updates

Codex rerouting for Functions are were done 410 of 1069 (38.4%). Almost all credits in this week are @stevenlinx.

Handbook Revamp

@leogermani started document for reviewing Handbook: http://wayback.fauppsala.se:80/wayback/20200330064509/https://docs.google.com/document/d/1X6MiAD7qpdEEMAfFE2pM_hFAynlPg0g5aOSa1em05O8/edit?usp=sharing

Everyone is welcome to review Handbook and leave feedback in document. Especially people new to the team. If Handbook makes no sense for them then we need to improve it. If you read handbook and have no idea what is project about or how to contribute to it, it means the handbook is poorly covering the project. Anyone should be able to start contributing after reading it.

First tasks are Welcome message, which is really outdated, and Handbook home page (as Welcome message links to it). Deadline for this is 7 days from today. @leogermani will gather all the feedback.

New value/motto to the Docs team – Better now than perfect tomorrow.

Leave feedback in the document, please.

Outliers in Codex

Specifically talking about Codex pages which are neither Theme, Plugin or API specifics, e.g. http://wayback.fauppsala.se:80/wayback/20200330064509/https://codex.wordpress.org/Converting_Database_Character_Sets

Plan is to first identify these pages on a list so that we can describe what they are doing as a group and figure out where to put them.

Suggestions are that we just create “Misc Handbook” and move pages there as we discover them or to make a list of all pages first.

We’ll postpone this decision until the time we have 10 such pages identified. Someone should take ownership of this and we will discuss it on next meeting.

Policy for External Linking

There is an ongoing discussion about this: http://wayback.fauppsala.se:80/wayback/20200330064509/https://make.wordpress.org/docs/2020/03/16/external-linking-in-docs-policy/

Everyone is welcome to participate in discussion.

Documentation License

There is an ongoing discussion about this: http://wayback.fauppsala.se:80/wayback/20200330064509/https://make.wordpress.org/docs/2020/03/16/documentation-license/

Everyone is welcome to participate in discussion.

Categorization Project, Alterations Workflow

HelpHub article can be found in several categories, but @estelaris‘ research has proven that this is very bad for usability. Essentially we’re categorising poorly and therefore there is such a need to categorise them multiple times.

Here is the document to illustrate this research: http://wayback.fauppsala.se:80/wayback/20200330064509/https://docs.google.com/spreadsheets/d/1lNxlyouZ9N6NuwA21lld3t_TZ6T–TVQGzB8fdjBl-M/edit?usp=sharing

The classification we have has been inherited from Codex and it is a classification from 15 years ago. It may have worked at some point but as we add new articles, it makes no sense any more.

However, we cannot disrupt the structure as we have millions of users that are familiar with the structure but we can make smaller changes to adapt and make it easier to search for users and even for Google.

Here is the post to explain the project: http://wayback.fauppsala.se:80/wayback/20200330064509/https://make.wordpress.org/docs/2020/02/21/findings-in-the-reclassification-of-wordpress-org-documentation/

We need to set real goals and clear tasks/workflows for this project. Document for following process: http://wayback.fauppsala.se:80/wayback/20200330064509/https://docs.google.com/spreadsheets/d/1_Ea2yeF5Rfy_YDk7pBRJ4rdljhMjygXFqBq8gWwhbaE/edit?usp=sharing

First we are going to define “Discoverability” and set few user stories. A dedicated meeting will be held for this. @milana_cap volunteered to help @estelaris with this.

Open Floor

@sukafia proposed adding HelpHub category or article on extending WordPress. What it is and what it can be used for. It is suggested that @sukafia review HelpHub article where this info could fit and add suggestions for edit. @softservenet volunteered to help.

Transcript of the meeting: http://wayback.fauppsala.se:80/wayback/20200330064509/https://wordpress.slack.com/archives/C02RP4WU5/p1584370804344000

External Linking in Docs Policy

Documentation at WordPress.org has a large number of external links mostly added to Codex and then copied to all other/new parts of docs. We have to decide on policy for external linking. Do we allow it and, if so, what is the criteria?

Even though external linking, as an idea, should be used for more in-depth explanation of the subject, things to consider:

  • External links need to be reviewed by our team members which is more work but more importantly, could cause our members unwanted situations when link is rejected
  • External links tend to be outdated (sooner than we expect)
  • We have no control if content on external link gets changed after approval, regular checking is highly undesirable another task for docs team
  • External links have been (and will be) used for gaining traffic and/or marketing own services
  • There’s probably more

We have to decide “yes” or “no” for external linking. Let’s keep in mind that documentation should be self sustained; our team members are not responsible for the content outside of WordPress.org but are responsible for the content inside of it.

Please leave your thoughts, as well as pros and cons in comments. Thank you.

My personal view, as I pointed out few times in slack, is that we should consider docs user in every decision we make. Of course, I don’t want more redundant work for our team members but I, also, think that we can avoid it and have valuable external links.

Current problems with external links are unreliable sources and/or authors. I’m 100% on removing and rejecting those, no question. However, we have a lot of smart and knowledgeable people in our community, members of docs and other teams.

If a member of make team (member and contributor, not only contributor) writes an in-depth article on the topic that is highly relevant for member’s team area, I think it’s rather safe to include it.

Maybe HelpHub doesn’t need such in-depth explanations but DevHub surely does. We want to set examples of best practices and promote deep understanding of how WordPress ecosystem works. It’s difficult to cover all that in our documentation for various reasons (lack of docs structure to support it, lack of such deep experts knowledge among people who write docs etc).

I believe our users could benefit greatly from this while we don’t have to worry about source’ and author’s reliability.

I think the only danger here could be if link dies, in which case someone will report it, just as people did so far.

External links are the foundation of the World Wide Web, to disallow them is to is to reject the basic premise of the web.

Wikipedia has a very comprehensive policy that should serve as a starting point http://wayback.fauppsala.se:80/wayback/20200330064509/https://en.wikipedia.org/wiki/Wikipedia:External_links it notably includes provisions for accessibility (both a11y and geo-walls).

Perhaps for .org there needs to be a clear and simple process for approving external links by a maintainer. This doesn’t need to be complex.

I would call the Wikimodel a nice idea, but impractical and it leads to a kind of power-trip if you’ve ever watched a wiki edit war between two editors, who both feel like their PoV of what makes something ‘notable’ is the only valid one. What makes something ‘notable’ is an insane level of over-moderation on Wikipedia. It’s part of why I stopped actively contributing 10 years ago, and it’s only gotten worse.

Thankfully we’re in a different situation. That is, we actually do know what sources are reliable and what are less so.

I would say allow ALL links (hear me out) but have them flagged as ‘reliable’ or ‘useful but possibly suspect’ and ‘unverified.’

To do that, we would curate a list of DOMAINS that we know to be good and safe. Like WPBeginners would be a reliable link, while Wikipedia and StackOverchange would be the next level down (because they’re not peer reviewed). Basically we come up with ‘levels’ of trust and apply them. If something’s not on a list, it’s ‘unverified’ and comes with a warning that the source has not been vetted.

That takes the onus off us from approving right away, and puts in on a long-term curation.

Bonus? We could apply this to the forums eventually as well!

Documentation License

There’s been a discussion lately about licensing all the documentation on wordpress.org. The task is to decide under which license we are publishing documentation.

Codex is under GPL v2 and a large part of out current documentation is copied from there. However, since then new Handbooks have been written on wordpress.org: CLI is under MIT while REST API still has no license but its rep, @kadamwhite, is comfortable with GPL.

As GPL is more appropriate license for code we are considering multi-license for documentation. We definitely want to keep GPL in case we need to embed it in WordPress (software), as recommended by @matt. Another license could be more appropriate for documentation; e.g. GFDL or CC0 (under which is Stack Overflow).

While deciding on this matter, we have to answer these questions:

  • How is WordPress documentation used and how it can be used?
  • What are forms of docs distribution?
  • What are freedoms we want to ensure for docs users?
  • What are restrictions, if any, we want to pose on docs users?
  • Did I miss anything?

Please feel free to post your thoughts/questions in comments below. We need as many people involved as possible. Thank you.

+make.wordpress.org/community/
+make.wordpress.org/accessibility/
+make.wordpress.org/core/
+make.wordpress.org/design/
+make.wordpress.org/marketing/
+make.wordpress.org/meta/
+make.wordpress.org/plugins/

Hi Milana,

It would be great if we could read the documentation directly into our WordPress site. I believe it can be done using the WP REST API as handbook is using a post type.

The freedom to read, extract parts and quote them.

Yes, opening docs with REST API (and some other parts of wp.org) is on my wish list too.

That would be “CC0”, not “CCO” like you wrote there. Zero, not the letter O.

CC0 is basically unlicensed. It’s as close to “do whatever you want with it” as can possibly exist.

Generally speaking, we have licensed all docs on the codex and everything else with the GPL and are comfortable with that regardless of its “code” nature. There is no reason to change that, as I see it.

That would be “CC0”, not “CCO” like you wrote there. Zero, not the letter O.

Thanks, fixed now.

Technically yes, we can use GPL for a manual/documentation, but per the GPL itself, the GNU Free Documentation License (GFDL) is recommended. That would allow us to use GPLv2 code snippets in the documentation, while giving more freedom for use (to whit — reusing content in for-profit works).

http://wayback.fauppsala.se:80/wayback/20200330064509/https://www.gnu.org/licenses/gpl-faq.en.html#WhyNotGPLForManuals

Agenda for Docs Team Meeting 16 March 2020

Our next Documentation Team meeting is scheduled on: Monday, March 16, 2020 at 03:00 PM UTC in the #docs channel on Slack.

  1. Attendance
  2. Notetaker & Facilitator selection
  3. Project Updates
  4. Handbook Revamp (outdated items)
  5. Outliers in Codex (non-theme or plugin)
  6. Policy for External Linking (continued discussion)
  7. Licensing (continued discussion)
  8. Categorization Project, Alterations Workflow (discussion)
  9. Open Floor

Summary for Docs Team Meeting: 09 March Meeting

The agenda for this meeting is on the http://wayback.fauppsala.se:80/wayback/20200330064509/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 GPL. 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 API handbook, but The CLI handbook is licensed under the MIT.

@Kenshino (Jon) strongly recommends each representative for projects in Docs to chime in Theme Handbook, Plugin Handbook, WP-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 http://wayback.fauppsala.se:80/wayback/20200330064509/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 (http://wayback.fauppsala.se:80/wayback/20200330064509/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 hooks 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 ping 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.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 P2 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 http://wayback.fauppsala.se:80/wayback/20200330064509/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 API handbook. It isn’t unique to plugins or themes. The Plugins handbook needs a deeper refactoring.

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

s
search
c
compose new post
r
reply
e
edit
t
go to top
j
go to the next post or comment
k
go to the previous post or comment
o
toggle comment visibility
esc
cancel edit post or comment
0
:)