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:

• WordPress Documentation Style Guide
• GitHub project repository – WordPress Documentation Style Guide
• Google Season of Docs original project proposal for tacitonic (Atharva Dhekne) – Google Developers

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 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 by 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. https://www.php.net/manual/en/index.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).

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

• Introduction
  • Changelog
  • Highlights
• General guidelines
  • Document structure
  • Style, voice, and tone
  • Accessibility
  • Global audience
  • Inclusivity
  • Facts and claims
  • External sources
  • Contributing to the Style Guide
• Language and grammar
  • Abbreviations
  • Articles (a, an, the)
  • Capitalization
  • Clauses
  • Contractions
  • Direct and indirect speech
  • Grammatical person
  • Nouns
  • Plurals
  • Possessives
  • Prefixes and suffixes
  • Prepositions
  • Pronouns
  • Tense
  • Verbs
  • Voice
  • Word Choice
• Punctuation
  • Apostrophes
  • Colons
  • Commas
  • Dashes
  • Ellipses
  • Exclamation points
  • Hyphens
  • Parentheses
  • Periods
  • Question marks
  • Quotation marks
  • Semicolons
  • Slashes
• Formatting
  • Dates and times
  • Examples and scenarios
  • Filenames, file formats, and types
  • Footnotes
  • Headings and titles
  • Key terms
  • Lists
  • Media
  • Numbers
  • Notices
  • Obsolete content
  • Phone numbers
  • Procedures and instructions
  • Tables
  • Text formatting
  • Trademarks
  • Units of measurement
  • Words as words
• Linking
  • Cross-references
  • External links
  • Headings as link targets
  • Image links
  • Link text
• Developer content
  • Code examples
  • Code in text
  • Coding standards
  • Command-line syntax
  • Placeholders
  • UI elements and interaction
• Word list and usage dictionary
  • Numbers, Symbols, A-Z

Research and references

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

• Google Developer Documentation Style Guide
• Microsoft Writing Style Guide
• Apple Style Guide
• IBM developerWorks editorial style guide
• Red Hat technical documentation style guide
• Mozilla Writing style guide
• The Chicago Manual of Style
• American Heritage Dictionary
• Merriam-Webster Dictionary
• WordPress Glossary
• WordPress Jargon Glossary – Make WordPress.org Marketing
• Handbook – Make WordPress Documentation
• WordPress Developer resources

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 refreshed my grammar memory and satisfied my appetite for meticulous punctuation.
• I learnt a great deal about accessibility, and how most of us don’t even consider how impactful it might be to many individuals.
• WordPress is a global project and working with the WordPress community gave me a unique global perspective. I wrote documentation with the likelihood that it would be translated to hundreds of locales.
• As is my bland vocabulary, I learnt hundreds, if not thousands of new words by searching for synonyms.
• I rejoiced writing down minute technicalities in Punctuation and Formatting.
• I adopted the Oxford/Serial comma in my writing.
• I learnt hundreds of new concepts that would certainly benefit me in the course of time. A few of them:
  • Command-line syntax
  • Heading targets
  • Trademarks
  • Straight and curly (typographer’s) quotation marks
  • Acronyms, initialisms, contractions, and shortened terms
  • Inclusive documentation
• Being probably the last generation that uses fax, I learnt that it is an abbreviation of facsimile.
• I explored more music genres and expanded my playlists while writing articles. 😛

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