This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- WordPress
- Technical writer:
- tacitonic
- Project name:
- A Full and Renewed Set of Documentation Style Guide
- Project length:
- Long running (5 months)
Project description
Synopsis:
WordPress is a global non-profit software organization that is dedicated to serving the global communities with software that emphasizes 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/individual; and WordPress serves an immense task of efficiently serving hundreds of millions of users - attributed to the 35% 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. The current WordPress documentation doesn’t include a universal & unified set of rules and style guidelines for publishing. The motive of this proposal is to create a full and renewed set of documentation style guidelines, universally applicable for WordPress documentation. The project idea involves consolidating all aspects of design and style guidelines like semantics, syntactics, grammar guidelines, punctuation, development-specific rules, design attributes and formatting specifics. It also incorporates language conventions like voice, tone, tense, all parts of speech, as well as naming conventions. The tools, languages and platforms used will be WordPress CMS, GitHub, Markdown and may also consist of PHP/MySQL, HTML/CSS and JavaScript.
Project Plan:
Current 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 doesn’t exist any fixed standard and criterion for the purpose of writing and publishing articles for WordPress. The documentation team has written project specific style guidelines, but none that are universally applicable. Most style guidelines that exist are not consolidated in one handbook, or are deprecated and need to be updated. Hence, there is a need to design and develop a unified style guide to standardize WordPress documentation.
Objectives:
Over 35% 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 proposal is to standardize a design & 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:
As suggested by the mentor (Jon Ang) for this project, the project can be approached in 4 phases: Discovery, Definition, Implementation and Maintenance phase. Before commencement of the project, during the pre-internship period, I will work with my mentor and finalize a suitable schedule and timeline going along the lines of my ensuing timeline & deliverables. I will familiarize myself further with the WordPress system and the work protocols for this project.
As the internship commences, I will discuss and draft the abstract of the plan with my mentor. The requirements and necessities will be determined. Firstly, I will outline the flow of the documentation and the user interaction process. Subsequently, the layout wireframes of each section, category and component will be outlined. These layouts will then be reviewed by my mentor. If required, the layouts will be redesigned and some components added/removed. I will then conduct user research for determining usability and feasibility of the interface flow. Subsequently, the Documentation Style Guide will be implemented (as illustrated in the diagram below) per section. Style guides from other organizations that are under any open source or Creative Commons licenses can be referenced to append our guide as well. If during this period, any usability difficulties occur, I will redesign them.
Testing and optimizations will be carried out after the style guide is completed and integrated with HelpHub. Any vulnerabilities, redundant elements or components would be rectified. UI and code testing will be carried out and unwanted bugs & errors will be fixed, if required. A final quality control for the complete style guide will be conducted for language, grammar, spellings, punctuation, etc.
Tasks pending due to unforeseen delays would be completed in the buffer period. Additional functionalities or features that would be determined feasible along the course of the project can be implemented after final testing is done. A deployment plan would be constructed and the finished product will be submitted.
Tools & Methodologies:
The documentation will be compiled and edited on a collaborative platform, such as Google Docs. If required to publish via GitHub, markup languages like Markdown or GitHub Flavored Markdown can be implemented as well. For design and style standards, open source style guidelines can also be referenced. Finally, the completed document would be formatted and published utilizing WordPress.
Component Table:
This is an exhaustive list of components that can be implemented in the Style Guide. Document Guidelines - Accessibility, Document Structure, Encoding, External Sources, Facts, Fonts, Global Audience, Inclusivity, Legality, Multi-platform Accessibility, Non-ambiguous, No Excessive Claims, Page Layout, Political Correctness, Protocols, Security, Sentence Structure, Succinct Writing, Tone & Style, Unbiased
Language & Grammar - Abbreviations & acronyms, Affirmation & Negation, Articles, Capitalization, Clause, Direct/Indirect speech, First/Second/Third person, Genders, Glossary, Nouns, Prefixes & suffixes, Prepositions, Pronouns, Referencing, Slang & jargon, Spellings, Technical terms, Tense, Verbs, Voice
Punctuation - Apostrophe & Quotation Marks, Colons & Semi Colons, Commas, Ellipses, Exclamation Marks, Hyphens & Dashes, Parentheses, Periods, Question Marks, Slashes
Formatting - Abstracts, Introduction, Prefaces, Brand Names, Product Names, Captions, Code Snippets, Code Blocks, Date & Time, Time Zones, Places, Currencies, File Names, Footnotes, Headings & Titles, Highlighting (Bold, Italics, Underline, Strikethrough, Quotation), Indentation, Index, Links & URLs, Lists, Bullet Points, Numbering, Media (Images, Videos) & Illustrations, Notes, Warnings, Tips, Numbers & Phone Numbers, Polyglots, Translation, Language Scripts, Spacing, Tables, Text, Trademarks, Copyrights, Patents, Citations, Tutorials & Procedures, UI elements, Units of Measurement
User Interface - Activities, Buttons, Code Snippets, Code Blocks, Command Line Interface, Dialogs, Menus & Dropdowns, Pop-ups & Alerts, Tabs, Terminology, UI elements, Windows
Code - CSS, HTML, JS, Markdown, MySQL, PHP, Syntax, XML
Word Usage Dictionary/Glossary - A to Z