wordpress/wordpress-documentation-style-guide

Style Guide for WordPress documentation.

WordPress Documentation Style Guide

The WordPress Documentation Style Guide is one of Google Season of Docs' projects for 2020.

• Technical writer: Atharva Dhekne (@tacitonic)
• Mentors: Felipe Elia (@felipeelia) and Milana Cap (@zzap)

Quick links:

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

Proposed elements/components in the style guide

Status	Description
🔄	In progress
✔️	Completed
❌	Discarded
⚠️	Needs changes

Style guide introduction (New section) ✔️

Component	Status
WordPress style guide	✔️
Style guide highlights	✔️
Other resources	✔️
Changelog	✔️

Document guidelines ✔️

Component	Status
Accessibility	✔️
Document structure	✔️
Changes to the guide (New component)	✔️
Encoding	✔️
External sources	✔️
Facts	✔️
Fonts	✔️ (Moved to Formatting)
Global audience	✔️
Inclusivity	✔️
Legality, licensing, trademarks	✔️ (Moved to Formatting)
Multi-platform accessibility	✔️
Non-ambiguous, no excessive claims	✔️
Page layout	✔️
Political correctness	✔️
Protocols	✔️
Security	✔️
Sentence structure	✔️
Succinct writing	✔️
Tone and style	✔️
Unbiased	✔️

Language and grammar ✔️

Component	Status
Abbreviations and acronyms	✔️
Affirmation and negation	❌
Articles	✔️
Capitalization	✔️
Clause	✔️
Contractions (New component)	✔️
Direct/indirect speech	✔️
Genders	✔️ (Moved to Pronouns)
Glossary	(Moved to Word Usage Dictionary)
Grammatical person	✔️
Nouns	✔️
Plurals (New component)	✔️
Possessives (New component)	✔️
Prefixes and suffixes	✔️
Prepositions	✔️
Pronouns	✔️
Referencing	✔️ (Moved to Formatting)
Slang and jargon	✔️ (Moved to Word Choice)
Spellings	✔️ (Moved to Word Choice)
Technical terms	✔️ (Moved to Word Choice)
Tense	✔️
Verbs	✔️
Voice	✔️
Word choice (New component)	✔️

Punctuation ✔️

Component	Status
Apostrophes	✔️
Colons	✔️
Commas	✔️
Dashes (split from Hyphens)	✔️
Ellipses	✔️
Exclamation points	✔️
Hyphens	✔️
Parentheses	✔️
Periods	✔️
Question marks	✔️
Quotation marks (split from Apostrophes)	✔️
Semicolons (split from Colons)	✔️
Slashes	✔️

Formatting ✔️

Component	Status
Abstracts, introduction, prefaces	❌
Brand names, product names	✔️
Captions	✔️ (Moved to Media)
Code snippets, code blocks	✔️ (Moved to Code)
Currencies	✔️ (Moved to Numbers)
Date and time, time zones, places	✔️
Examples and scenarios (New component)	✔️
Filenames	✔️
Footnotes	✔️
Headings and titles	✔️
Highlighting (Bold, italics, underline, strikethrough, quotation)	✔️ (Moved to Text formatting)
Indentation	❌
Index	❌
Key terms (New component)	✔️
Links and URLs	✔️ (Moved to Linking)
Lists, bullet points, numbering	✔️
Media (Images, videos) and illustrations	✔️
Notices (Notes, warnings, tips)	✔️
Numbers	✔️
Obsolete content (New component)	✔️
Phone numbers	✔️
Polyglots, translation, language scripts	✔️
Referencing	✔️ (Moved to Linking)
Spacing	✔️ (Moved to Text formatting)
Tables	✔️
Text formatting	✔️
Trademarks, copyrights, patents, citations	✔️
Tutorials and procedures	✔️
Typography and fonts	✔️ (Moved to Text formatting)
UI elements	✔️ (Moved to User interface)
Units of measurement	✔️
Words as words (New component)	✔️

Linking (New section) ✔️

Component	Status
Cross-references	✔️
External links	✔️
Heading links	✔️
Image links	✔️
Link text	✔️

User interface (Moved to Developer content) ✔️

Component	Status
Activities	✔️
Buttons	✔️
Code snippets, code blocks	✔️
Command line interface	✔️
Dialogs	✔️
Menus and dropdowns	✔️
Pop-ups and alerts	✔️
Tabs	✔️
Terminology	✔️
UI elements	✔️
Windows	✔️

Developer content ✔️

Component	Status
Code in text (New component)	✔️
Code examples	✔️
Coding standards (New component)	✔️
Command-line syntax	✔️
CSS	✔️ (Moved to Coding standards)
HTML	✔️ (Moved to Coding standards)
JS	✔️ (Moved to Coding standards)
Markdown	✔️ (Moved to Coding standards)
MySQL	❌
PHP	✔️ (Moved to Coding standards)
Placeholder formatting (New component)	✔️
Syntax	✔️
Terminology	✔️
UI elements	✔️
XML	❌

Word list and usage dictionary ✔️

Component	Status
Numbers	✔️
Symbols	✔️
A	✔️
B	✔️
C	✔️
D	✔️
E	✔️
F	✔️
G	✔️
H	✔️
I	✔️
J	✔️
K	✔️
L	✔️
M	✔️
N	✔️
O	✔️
P	✔️
Q	✔️
R	✔️
S	✔️
T	✔️
U	✔️
V	✔️
W	✔️
X	✔️
Y	✔️
Z	✔️

Future components

Component	Status
Media > Videos
API reference documentation

wordpress-documentation-style-guide's Issues

Update heading anchors

Change branch names from 'master' to 'main'

https://github.com/WordPress/WordPress-Documentation-Style-Guide/blob/main/manifest.json

Articles without heading/topic list

• https://make.wordpress.org/docs/style-guide/language-grammar/possessives/
• https://make.wordpress.org/docs/style-guide/punctuation/parentheses/
• https://make.wordpress.org/docs/style-guide/language-grammar/articles/

Add external link icon for articles

Github edit button links to a 404

The Github link (next to the H1) to edit the page directly links to a 404 broken page- Example:
https://make.wordpress.org/docs/style-guide/linking/heading-targets/#adding-an-anchor

When clicking the Github Edit link by the title, it links to a 404 page. The url is mostly correct, if you replace 'master' for 'main in the url path it works.

Example Incorrect:
https://github.com/WordPress/WordPress-Documentation-Style-Guide/edit/master/docs/6-linking/heading-targets.md

Example Correct:
https://github.com/WordPress/WordPress-Documentation-Style-Guide/edit/main/docs/6-linking/heading-targets.md

Irregular bullet point in topic list for WWW

https://make.wordpress.org/docs/style-guide/word-list/w/

https://make.wordpress.org/docs/style-guide/word-list/w/#www

No heading anchor and subheading for "help"

https://make.wordpress.org/docs/style-guide/word-list/h/#help

Incorrect code fence parsing

• https://make.wordpress.org/docs/style-guide/formatting/headings/
• https://make.wordpress.org/docs/style-guide/formatting/media/
• https://make.wordpress.org/docs/style-guide/formatting/notices/
• https://make.wordpress.org/docs/style-guide/formatting/obsolete-content/
• https://make.wordpress.org/docs/style-guide/formatting/procedures/
• https://make.wordpress.org/docs/style-guide/formatting/tables/
• https://make.wordpress.org/docs/style-guide/linking/heading-targets/
• https://make.wordpress.org/docs/style-guide/linking/image-links/
• https://make.wordpress.org/docs/style-guide/developer-content/code-examples/
• https://make.wordpress.org/docs/style-guide/developer-content/placeholders/
• https://make.wordpress.org/docs/style-guide/formatting/units-of-measurement/

Review all titles and headings

Check whether all titles/headings are in the gerund form or action + object form.

Formatting issues in Formatting docs

I stumbled upon a few formatting issues related to how the markdown on GitHub is ingested into the actual https://make.wordpress.org/docs site.

There are probably more, but here are a few.

Headings and titles	Units of measurement	Media

Note

While the callout design has been updated recently, the functionality is the same as the previous design, so this does not appear to be a new issue.

Replace placeholder variables

Replace placeholder variables with <code><var>PLACEHOLDER</var></code>
See https://github.com/WordPress/WordPress-Documentation-Style-Guide/blob/master/docs/7-developer-content/placeholders.md#single-placeholder

"Writing inclusive documentation" review

Reviewing Writing inclusive documentation

Idioms

Write WordPress documentation considering inclusivity of people from all walks of life.

all walks of life is idiom used mainly in English language. There might be similar ones established in other languages but I can say for Serbian that we have nothing to match it and while I know what you're trying to say, I think it's better to rephrase that part to exactly what you meant by it. Especially because we can expect this style guide to be translated into all locales at some point.

Unbiased documentation

I'd love if we could get some examples on how to achieve points from this list.

Software language improvements

Can we include here other improvements done in software industry, such as abandoning "blakclist", "whitelist" and similar terms? Here's something already done by core team: https://make.wordpress.org/core/2020/07/23/codebase-language-improvements-in-5-5/

Similar happened at GitHub and other companies: https://www.bbc.com/news/technology-53050955

Add key points for all articles/components

Add key points at the beginning of the articles.

Complete internal linking for articles