Proposal: Handbook for Local Teams

tl;dr – Local teams, such as [es.wordpress.org] will be able to have their Handbook for a complementary use of the global Handbooks, but adapted to the particularities of the local culture instead of relying solely on a translation of the English version.

Currently, we could group the Handbooks into three types:

All these documents are in English and are maintained globally by some members of the WordPress Community.

But, in some cases, especially the local teams of each country, region or locale, there are specific documentation needs that cannot be added to the global Handbook. The clearest example is a contextual documentation of translations (the differences between English and Spanish, or between Spanish from Spain and Spanish from Mexico), or onboarding documentation for a Local Community (for example, access to their Slack).

To this, we can also add documentation from other teams that affect local elements, such as events, being able to share presentations or WordCamp information from a territory.

Three years ago, a pilot project was started in the WordPress edition of Spain for the installation of the same Handbook plugin that is used in Make/WordPress teams.

This technology is available on several sites, but with very different results. One of the biggest problems is who has access to the site and who can propose improvements or make changes, with blocking or access limitations.

That is why the following proposal is raised, based on how is already working on the Make/Hosting.

The Hosting team has a Handbook that for more than 2 years has been managed entirely from GitHub. This allows its management within WordPress to be limited to the Team Reps of the team, who perform operational tasks (ordering and reviewing content.) Because the management user is WordPress.org, the attribution of the contents is not made to any contributor.

How is content attributed to contributors? Through GitHub, since anyone who collaborates in the repository will have a versioning of the changes, and their attribution in the Activity Tab of their Profile, thanks to the synchronization between WordPress Profile and GitHub. Contribution to WordPress Documentation can be gamified.

And, an advantage and disadvantage at the same time, is how it is documented on GitHub: with the Markdown markup language. This language is a de facto standard used in many projects and allows the creation of textual content in a simple way from the keyboard (and easily convertible to HTML). It is also the native text language of GitHub, which allows editing directly from the platform itself, without the need to install an external program. And although it is simple to learn, it has the disadvantage that you have to learn the basic syntax, and that you have to know how to use GitHub, although it has already been proposed that this is the tool for massive use of the WordPress Community.

From here, through a simple configuration, considering that the Block Editor can interpret Markdown natively and that there is a tool (already tested in the Hosting team) that synchronizes every 15 minutes any approved change in the Handbook repository with the WordPress site, being able to anyone in the world contribute to a team with a standard tool, whether you have a WordPress account.

As a starting point, the WordPress Community Spanish Team has been working for some time on a Handbook in which team folders and other useful folders for the Community have been created (such a general GitHub manual), and to which anyone can contribute.

This repository must be under the WordPress organization of GitHub, and apply the synchronization tool between that repository and the Handbook plugin, already installed on the [es.wordpress.org] site.

From there, anyone who wants it can contribute to the Handbook with new content, new ideas or suggestions through the automated system.

This should extend to the current Locale Managers of a management team of the edition of the locale sites, called Local Team Reps, and following the same philosophy of the Global Team Reps, being the Documentation Local Team Reps responsible for the approval and management of the publication.

Nowadays, the project for the WordPress Community in Spain is very advanced, and it would be immediate to be able to launch the pilot program of automation of local Handbooks, started 3 years ago.


Proposal by @javiercasares. Reviewed by @amieiro, @anagavilan, @estelaris, @glycymeris, @milana_cap, @mrfoxtalbot.

+make.wordpress.org/meta/

+make.wordpress.org/polyglots/

Pinging all Local Teams with Handbooks available, and Spain.

+es.wordpress.org/team/

+af.wordpress.org/team/

+ar.wordpress.org/team/

+de.wordpress.org/team/

+en-ca.wordpress.org/team/

+es-mx.wordpress.org/team/

+fr.wordpress.org/team/

+id.wordpress.org/team/

+it.wordpress.org/team/

+ja.wordpress.org/team/

+pt-ao.wordpress.org/team/

+br.wordpress.org/team/

+ro.wordpress.org/team/

+sr.wordpress.org/team/

+yor.wordpress.org/team/

+tw.wordpress.org/team/

#handbook, #handbooks

Docs Chat Agenda – July 14, 2016

Here’s the agenda for the Docs team weekly chat, which are held Thursdays at 17:00 UTC in the #docs channel 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/..

Current Projects Updates:

  1. Theme Developer Handbook – @kenshino
  2. Codex MigrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. (DevHub) – @drewapicture
  3. DevHub – @drewapicture
  4. HelpHub – @kenshino
  5. Inline Docs – @drewapicture

Other Stuff:

  1. Internationalizing documentation
  2. Version articles (HelpHub)
  3. Hosted about pages
  4. Open Floor

#chat, #codex-migration, #handbooks, #helphub

4.1 Docs Updates

There are a number of updates that need to be made for 4.1 to both the handbooks and the Codex.

Handbooks:

There are several posts on Make/CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. about changes in 4.1 that affect the developer handbooks:

Themes: New Template Tags in 4.1

Queries Improvements:

Shared Terms: An Update on Shared Term Splitting

CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. 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. Improvements: JS/Underscore-template-rendered Custom Customizer Controls in WordPress 4.1

I still need to add a list of Codex pages here that will need to be updated with the content from these posts.

Codex Updates:

The following are the pages that need updated or created in the Codex.

If you would like to help, please leave a comment indicating which page you would like to work on.

New default theme:

  • Twenty Fifteen page. We can use some of this content. Note: The custom color screenshots are slightly different from the .org version. Takashi Irie provided some screenshots that reflect the default colors available: https://cloudup.com/cNHOeJVOq-k (@kpdesign)

New features:

  • New Distraction-Free Writing and inline image editing toolbar in Post editor – https://codex.wordpress.org/Posts_Add_New_Screen and https://codex.wordpress.org/Pages_Add_New_Screen
  • New sessions logout button on Profile page – https://codex.wordpress.org/Users_Your_Profile_Screen
  • New Recommendations tab on Plugin Install page – https://codex.wordpress.org/Plugins_Add_New_Screen
  • New translation installation setting on General Settings and Network Settings pages – https://codex.wordpress.org/Settings_General_Screen and https://codex.wordpress.org/Network_Admin_Settings_Screen
  • Appearance menu – HeaderHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. and Background menu items now link directly to the Customizer.

#4-1, #codex, #handbooks

Handbooks Update: November 18, 2014

Present today were: @aj_mallory, @blobaugh, @grappleulrich, @naomicbush, @samuelsidler, @sewmyheadon, and @topher1kenobe.

Most importantly, the chat is moving to Thursdays at the same time. The next chat will be Thursday, December 4, 2014 at 21:00 UTC. We will not have a chat next week due to Thanksgiving in the US. Of course, we all idle in #docs 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/. if there are questions outside of our weekly chat.

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 developer handbook:

  • Launched version 1 at WCSF
  • Not much traction since
  • Focus going forward is getting minor issues (on the spreadsheet) taken care of, then onto reviewing the top Codex pages and bringing over any good information so we can redirect them.

Theme developer handbook:

  • Completely migrated since prior to WCSF.
  • Minor movement just after WCSF but mostly stagnant.
  • We need volunteers to own pages so we can get moving.

If you want to help with either handbook, 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.” any of us in #docs on Slack (especially @blobaugh@sam, @sewmyheadon, and @topher1kenobe).

Coming up on December 6 is the Docs Sprint in Seattle and in #docs on Slack.

#handbooks

WCSF 2014 Docs Contrib Day Notes

Purpose to see how we are doing on Docs and look towards the future

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

  • Almost complete. One page left to write
  • Siobhan is holding back launch with the intro 😉
  • Landing page on developer.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/ will be updated to unveil the plugin hb tomorrow!
  • How can we get feedback from the users on handbook pages?
  • Add list of pages from the codex that can be redirected or need content migrated into the spreadsheet

Theme handbook

  • At 67% completion
  • Future focus can be put completely on theme hb instead of splitting with plugins

Contributor days

  • Difficult to retain contributors
  • Takes a while to get them up to speed on how to contribute
  • Are still useful as contributors that do return contribute significantly

Developer.wordpress.org

  • Landing page will show the new theme
  • Theme hb link should be whited out and say coming soon
  • Need examples contributed to the code reference
  • Need a way to group together items in the functions reference. Possibly a tag that can be added. Scott (coffee2code) is looking into options
  • The JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. 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. docs need to be pulled in. Currently exist as markdown on GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/
  • Need a banner on the handbooks that lets users know all content is volunteer contributed and they can get involved

Future

  • Go through codex and find pages that can be relevant to the plugin handbook
  • Siobhan will provide list of high traffic codex pages that need to be checked for content and redirected to plugin handbook
  • Need list of content that is duplicated between both plugin and theme handbook (E.G 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/.)
  • Where should content live that does not exactly live in either handbook? (E.G list of javascript libraries built into WordPress)
  • Need a 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/. bot that will send messages to #docs when user wants to ask a question???
  • How do we easily let in new users to edit handbooks? This needs more discussion. Prefer to contact a human to get access. Preferably one of the editors
  • Will be implementing an issue tracking system that will contain tickets for things that need updated/added

Make.wordpress.org/docs

  • Instead of weekly meetings we should use the blog to post questions, get feedback, etc
  • Switch to monthly all docs team chats

#handbooks, #wcsf2014

Devhub Todo List for pre-WCSF

Prior to WCSF we need a few changes on devhub so that y’all can make awesome handbook improvements as your project. I’ve come up with a list of things that seem important prior to WCSF. This list may not be exhaustive, so we’ll add to it as we come up with other things. In general, the following are in list by importance.

  • Fix image uploads on devhub, which is currently preventing us from migrating the theme developer handbook.
  • Add the Mediawiki 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 for external redirects so we can redirect Codex pages to devhub (#meta446)
  • Add voting to examples (#meta551)
  • Create a new user role for handbook editors (#meta621)
  • Add the code TinyMCE plugin to devhub
  • Various handbook design changes (#meta631)
  • Improve the design of the callout shortcodes (#meta630)

#devhub, #handbooks

Handbooks Update: September 23, 2014

Present today were @blobaugh, @sewmyheadon, and @topher1kenobe, with a few devhub peeps following along as we overlapped slightly. Logs are here.

  • 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: Topher worked on section 8 (metadata) and section 9 (CPTs and taxonomies) and both are now at 100%. Ben will be out of town for the next two chats.
  • Theme handbook: No updates this week. Hopefully some more next week.
  • MigrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. update: A bunch of the plugin handbook has been migrated with more being migrated this week.

If you want to get involved in either handbook, please email any of us.

Again, we meet on Tuesdays at 20:00 UTC. Hope to see more people there!

#handbooks

This weekend @sewmyheadon is hosting a Documentation Sprint…

This weekend @sewmyheadon is hosting a Documentation Sprint in Seattle. If you are in the area and would like to join in person join us at Uptown Espresso on Westlake. If you are remote please join us in #wordpress-sfd on Freenode.

For full details see the Meetup post at http://www.meetup.com/SeattleWordPressMeetup/events/196326602/

#handbooks, #plugin, #sprint, #theme

Weekly Handbook updates I ran the handbook chat…

Weekly Handbook updates

I ran the handbook chat for @samuelsidler yesterday while he was out. Present were @blobaugh @jerrysarcastic @topher1kenobe @sewmyheadon

The theme handbook is coming along. This weekend is another of the monthly doc sprints and @sewmyheadon is hoping to knock out a good chunk of the handbook.

A couple more sections of 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 have been marked 100% or are ready for review. Thanks again to @topher1kenobe for doing much of the heavy lifting!

MigrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. to the new devhub has been going slowly but has had some progress.

In addition to the monthly doc sprint in Seattle hosted by @sewmyheadon there will also be a general 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/. in Tacoma starting soon. Also led by @sewmyheadon. What a great guy!

The handbooks are still a work in progress and we are always happy to have more contributor, either writing content, editing, proofing, testing, or other! If you would like to help out please contact @samuelsidler @blobaugh or @sewmyheadon

#handbooks

Handbooks Update: August 20, 2014

We had our weekly chat today with @blobaugh, @jerrysarcastic, @sewmyheadon, @topher1kenobe, and myself in attendance (log here).

Both handbooks received quite a bit of attention during the 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. Grand Rapids and WordCamp Maine contributor days.

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 Developer Handbook:

  • Some progress made over the last week.
  • A lot of things at 90%+ that need final edits.
  • Focus is on getting sections completed one-by-one.
  • Each section will need an “introduction” added. Some of them already exist.

Theme Developer Handbook:

  • A second docs meetupMeetup All local/regional gatherings that are officially a part of the WordPress world but are not WordCamps are organized through https://www.meetup.com/. A meetup is typically a chance for local WordPress users to get together and share new ideas and seek help from one another. Searching for ‘WordPress’ on meetup.com will help you find options in your area. in the Seattle area is going to be setup starting in October or so.
  • Eric would like a second person to help lead the handbook, specifically someone who can work with other volunteers.
  • Like the plugin handbook, we’ll need introductions for each section.

For both handbooks, our focus is on getting things done faster and not making them “perfect.” We’ll edit as needed on the live site, but it’s important to get what we have in a usable state and get it live soon. Migrated pages will be blanked out on the staging site (make/docs) so we don’t modify them further.

Finally, I updated the “Handbooks” page on the docs contributor handbook. That page and its subpages (including the style guide) need review and editing so we can help onboard new contributors.

Would it help to have contributors join our weekly chats? Or perhaps to have a weekly, online handbook sprint? What does the docs team think?

#handbook-chat, #handbooks