Agenda for Documentation Team Meeting 29 June 2021

The next meeting is scheduled with the following details:

When: Tuesday, June 29, 2021, 14:00 UTC

Where#docs channel on Slack.

Meeting Agenda:

  1. Project Updates
  2. New Member Mentoring
  3. An Audit Tool (proposed by the Training Team)
  4. Doc update for 5.8 update release
  5. DevHub & HelpHub updates
  6. Doc Team is looking 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 Docs Project Lead
  7. Open Floor

Please feel free to suggest agenda items by commenting on this post or by raising it during Open Floor.

Thank you!

#meeting-agenda

Agenda for Documentation Team Meeting 8 June 2021

The next meeting is scheduled with the following details:

When: Tuesday, June 8, 2021, 14:00 UTC

Where: #docs channel on Slack.

Meeting Agenda:

  1. Project Updates
  2. New Member Mentoring
  3. Theme Handbook changes
  4. An Audit Tool (proposed by the Training Team)
  5. A tighter partnership between CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. & Docs (as proposed by @milana_cap and @mkaz)
  6. We need a new 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 User Docs Project Lead!
  7. Open Floor

Please feel free to suggest agenda items by commenting on this post or by raising it during Open Floor.

Thank you!

Docs Meetings Day

Recently Docs team voted on meeting time as it was overlapping with business obligations for some members. We changed it but the problem persists and now we are looking into changing the day.

So, here we are voting for the same time but different days. Wednesday is already filled with other meetings at 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/ so let’s see how we stand with:

  • Tuesday 2PM UTC
  • Thursday 2PM UTC
  • Friday 2PM UTC

Please leave your prefered day in the comments below. Thank you.

Discussion: April 2021 Coffee Break

The monthly coffee break for the Documentation Team is back again!

What is a Virtual Coffee Break

Coffee Breaks are informal discussions taking place in a Zoom call for 30 minutes among regular and new contributors to the Make WordPress Docs Team. We have an ongoing agenda which can be traced back to the most recent meeting summary to help facilitate the process. Currently @sukafia and @chaion07 are volunteering with the responsibilities. We’ve also had @estelaris hosting one the coffee break for November last year. Join the next coffee break and express your interest should you wish to host one.

Since the February 2021 Coffee Break, we had to skip the one for March 2021 as many contributors were unavailable including both @sukafia & @chaion07 were experiencing circumstances beyond control. Now we welcome you to share your thoughts on the April Coffee Break. Please comment below to let us know your thoughts on the Virtual Coffee Break that began during the global pandemic in 2020.

  • Choose the date for the Coffee Break: 27, 29 or 30 of April (intentionally skipped 28 since Wednesdays are packed with meetings😅)
  • Preferred time-zone: EU, US, APAC, etc.
  • General comments or concerns (if any)

Props to @sukafia for the peer review!

#coffee-break, #meetings

Agenda for Docs Team Meeting April 19, 2021

The next meeting for the Make WordPress Global Documentation Team is scheduled with the following details:

When: Monday, April 19, 2021, 14:00 UTC

Where#docs channel on Slack.

Meeting Agenda:

  1. Project Updates
  2. Team goals updates
  3. New Member Mentoring
  4. Google Season of Docs
  5. Unified Doc License page
  6. Author attribution to docs
  7. April Coffee Break
  8. Discussion about the process gap between dev notes release stage and docs team writing about a feature, review last weeks’ discussion
  9. Open Floor/Q&A

Please feel free to suggest agenda items by commenting on this post or raise during the open floor.

Thank you!

#agenda#meetings

#meeting-agenda

Call for projects ideas for the Google Season of Docs 2021

Note: UPDATE: Refer https://make.wordpress.org/docs/2021/03/26/google-season-of-docs-2021-project-ideas-list/ for the final project list for Season of Docs 2021.

Got any ideas for WordPress documentation projects for the Google Season of Docs? Share them with us! Project proposals should be in such a way that they can benefit from the work of the technical writers.

Please share your project ideas by Wednesday, March 24, 2021, UTC 11:59.

#season-of-docs-2021

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

Call for mentors for the Google Season of Docs 2021

If you’ve been reading the Make/Docs blog this week, then you already know that WordPress will be applying for the Google Season of Docs 2021.

In order to help the technical writers with the projects they will be choosing, it would be ideal if they were accompanied by one or more mentors who have some experience with WordPress documentation. Although it is not mandatory for this edition of the program, we think it could be very beneficial.

If you would like to learn more about the role of a mentor, please read this guide for program mentors.

If you are interested in being a mentor, please mention it in a comment to this post with Wednesday, March 24, 2021, UTC 11:59.

#season-of-docs-2021

Google Season of Docs 2021 – Project ideas list

Note:

Our application was not accepted for this edition of the Season of Docs. I received the email from Google on Friday, April 16th notifying me of this.

However, the projects we submitted will be highly beneficial to the documentation team, and to WordPress in general. So I’m very interested in leading/working on some of them, and also in supporting contributors who would like to do the same.

In the next few days, I’ll get in touch with the people who were interested in participating in this Season of Docs, and, if they are still interested, see how we can move forward.

Below is a list of projects presented by WordPress for Google Season of Docs 2021. Prospective technical writers can also suggest new project ideas in the comments section.

People involved:

Project list

Project one: @justinahinon

Project name: Create a system to track updates and suggestions to the WordPress documentation

Project description

The problem: The WordPress documentation is huge and divided into multiple sections. There is user documentation and developer documentation of different projects (themes, plugins, block editor, APIs, etc.).

All this documentation is subject to frequent changes as the projects to which they belong evolve. So we end up with requests for changes, requests for updates that are frequently reported on various channels: Slack, Meta Trac, GitHub, etc.

The fact that we don’t have a unified system for change requests and documentation updates makes collaboration difficult; and can be an obstacle for new contributors who want to start with documentation contribution.

So, WordPress really needs to have a unified tracking system so that we can track these requests and the work to fulfill such requests. And we need to create a process to utilize this system properly.

Measuring the project’s success

The main indicator of success is the effective implementation of a system and process to report documentation that is obsolete, needs to be updated or corrected.

The second indicator of success is the use by contributors of the system and process implemented.

Required skills

The technical writer who will work on this project should have an idea of WordPress documentation, how they work, and how the documentation team maintains them.

The technical writer will have a mentor with experience on the documentation team, who can provide assistance and guidance as needed.

Project two: @chaion07

Project name: Documentation for a better on-boarding experience: Supporting new contributors to WordPress

Project description

The problem: Reported by W3Techs WordPress currently powers over 40% of the web. The WordPress Org comprises of contributors and the number is growing by the day. With 18 Make WordPress Teams it can be a daunting experience for new contributors in finding their place. Many teams have their on-boarding documentations as part of the Handbook. Some are automated, for example the core team while others lack enough clarity for new contributors to understand.

Thus, WordPress should include both technical and other know-how documentation for contributors. Season of Docs is the perfect excuse to improve each of the 18 teams’ handbooks emphasizing on the contributor on-boarding experience.

This project aims to improve the documentation of the on-boarding experience for contributors. With rich, interactive content including multilingual videos, the goal is to support the existing documentation from individual team’s handbooks and to standardize them in a way that can be truly beneficial for the contributors.

Measuring the project’s success

Adding relevant section to the handbooks and those pages would be the main success criteria for the project. Being able to include localized content can also help improve the overall user experience and reach a wider audience.

An additional success criteria for the project can also be on the use of the content and in the implementation of the content when put to the test.

Required skills

The technical writer should have an understanding on the following:

  • How Make WordPress Teams function
  • Weekly Meetings and Triage Sessions
  • Workflow of the Make WordPress Teams
  • How to propose changes for the Handbook
  • How WordPress is being improved (release process)
  • Where to ask for help and how to avail them
  • Identifying the contact person for each Make WordPress Teams

The technical writer can have a mentor with experience on the documentation team, who can provide assistance and guidance if needed.

Related Material

Project three: @tacitonic

Project name: Write Gutenberg block editor end-user documentation

Description

There are gaps in the existing documentation for the Gutenberg block editor with missing pages and existing pages that need to be updated – as 80% of them haven’t seen an update since WordPress 5.0 came out. With constant UI changes on for every version, Gutenberg block editor documentation is evolving rapidly with new version releases.

Required skills

A content creator’s (blogger, writer) understanding for the block editor; no development skills are required.

Related material

Project four: @tacitonic

Project name: Improve existing user and developer documentation and handbooks

Description

We have a lot of developer documentation. WP Core’s documentation is mostly automated. However handbooks that describe how one would create a theme, make a plugin, use the REST API, or automate things via the CLI do not receive updated documentation. In turn, this requires that all handbook maintainers know all the changes in each core release to be able to write something useful.

In some cases, the handbooks are updated but don’t provide enough examples for new developers to get started. We would like to close these gaps.

Another improvement would be to adopt the newly published WordPress Documentation Style Guide for existing documentation.

Related material

Project five: @mkaz

Project Name: Extending block editor developer documentation

Description

Documentation on developing on top of block editor is, depending on the topic, either scarce, outdated, or non-existent. Considering that the block editor is a significant language leap for WordPress developers, the project itself would benefit from having detailed documentation in a form of guides or tutorials, on how to utilize and extend core functionality and what the best practices are.

Related material


Additional information

  • Previous participation in Season of Docs, Google Summer of Code or others:
    WordPress participated in Google Season of Docs 2020. WordPress was also a mentoring organization for Google Summer of Code 2014.

#season-of-docs-2021

Recommendations for additional team leads

Hello all

We discussed this lightly in a team meeting 1.5 weeks ago but we did not managed to put this into writing.

I have recommended that @milana_cap and @atachibana become Docs’ Team Co-Leads alongside me. They’ve been doing some great work over the last 2 years and have really stepped up in the the team’s leadership and project management aspects.

If there are no objections, we’ll solidify this decision by 28 29 March 2021 (in our Docs team meeting).

Feel free to reach out to me on #docs or via DM if you have questions!