User Handbook

[chrisvanpatten]

This is a tracking ticket for the User Handbook. The goal is to use this ticket to get us to…

1. Consolidate discussion
2. Consolidate GitHub issues related to the user documentation into this ticket
3. Map PRs to sections of the handbook outline

This is the documentation outline that needs the most love and attention. I expect our documentation bug scrubs will flesh it out, but please feel free to comment with more ideas!

Outline

1. Meet the editor (high level UI overview)
   1. What is a block?
   2. Customising blocks
   3. Reusable blocks
   4. Plugins (how to find/access)
2. Manual for users of assistive technologies (Manual for users of assistive technology #10373)
3. FAQ
   1. How do I stick with Classic?
   2. What do I need to know about backwards compatibility?
   3. What's different about the new editor? (Document known changes in editor behavior #4186)
   4. Where do I report problems?

[0aveRyan]

Some basics that we're all probably used to it'd be great to spell out:

• All Paragraphs are their own Blocks
• Blocks can be converted into related Blocks
• There is a Classic Block for a familiar experience
• Saving posts no longer reloads the page

Some additional topics that'd be great to include for users:

• Using the Document Outline
• How the Sidebar Works (Show/Hide, Contextual, Document vs. Block, Plugins)
• Setting Editor Preferences via the Menu
• Using Editor Plugins

Some "hidden" features it'd be great to highlight:

• Terrific Copy/Paste support
• Using the Slash Inserter
• Using Keyboard Shortcuts
• Copy a URL, highlight text and paste to create a hyperlink from the selection

[0aveRyan]

Took another pass at this outline as well @chrisvanpatten

1. Introducing the New Editor
2. Creating & Managing Content
   1. Getting Started
   2. Quick Start
   3. Introducing Blocks
      1. Getting Started
      2. Insert Blocks
      3. Customize Blocks with the Toolbar & Sidebar
      4. Rearrange, Duplicate or Delete Blocks
      5. Transform Blocks
      6. Choose Block Styles
      7. Block Reference
   4. Introducing Reusable Blocks
      1. Getting Started
      2. Convert to Reusable Block
      3. Convert to Regular Block
      4. Manage & Delete Reusable Blocks
   5. Working with Templates
3. Personalize Your Editing Experience
   1. Using Spotlight Mode
   2. Using Fullscreen Mode
   3. Using Unified Toolbar Mode
   4. Using Custom Editor Plugins
4. Common Questions
   1. How do I keep the Classic Editor?
   2. Will this break my website? Is it compatible with old content?
   3. What’s new?
   4. I’m struggling with the New Editor, any tips?
   5. Where do I report problems?
   6. What should I expect going forward?
5. Reference
   1. Editor Diagram (labeled)
   2. Additional Resources
6. Help & Support

[chrisvanpatten]

@0aveRyan this is KILLER. It would be awesome to get some volunteers in here to pick a section or document and start writing. Is that something you want to kick-off?

[0aveRyan]

So I wanted to get an update out tonight with a few things:

1. Intro
2. Timelines
3. Priorities
4. Getting Involved
5. What to Expect

Intro

I'm Dave, I'm a (fairly new) WordPress contributor at Bluehost. I'm aiding @chrisvanpatten, who has taken up organizing this initiative. @abrightclearweb is bringing some incredible resources on part of the Accessibly Team, Edwin from Yoast (https://twitter.com/edwintoonen) has some great content, think @melchoyce is going to be trying to bring her skills. All are welcome, more below.

Timelines

• Thursday - we need to identify critical material and I'm not the best point person as I'm traveling Wednesday. I will be working but airborne. Hoping to post an outline from my layover.
• Docs Release v1 - release tbd but likely weeks not days
• what done looks like (over early 2019)

Priorities

• Show Gutenberg is a strong enough product to both benefit from and not always need documentation.
• Introduce a shared vocabulary and show users how new features and tools help them
• Demystify, suggest workflows, be helpful.
• Balance avoiding repetition with multiple ways of saying things.
• Provide an accurate, accessible, unassuming voice.

Getting Involved

We have User Docs (including an Accessibility section and universal theme). These will be on WordPress.org/support (HelpHub).

We also have Developer Docs on developer.wordpress.org. @chrisvanpatten can speak to this more than I can. We'd love devs to feel empowered to deploy, build for and extend the new code introduced in 5.0.

What To Expect

@chrisvanpatten has helped us build a really nice coalition to make this an initiative. He is guiding meetings and our project lead.

I'm available to this project from my company and working on helping organize, combine content and input content. We can use help in many departments once combined from disparate resources and during combination. Use the outline above for a rough idea, but also considerate of what we've done and iterating from there is the game plan.

We'd love to do some open edits! Zoom. Google Docs. I've done both with success. We also gotta ship things. We haven't planned this in advance, we've just been diving into docs as the code has stabilized. We're open to input and hope we can be a positive part of this transition!

[DrewAPicture]

cc'ing @coffee2code in regard to the Developer Hub stuff @chrisvanpatten is wrangling.

[melchoyce]

I'm happy to take screenshots and videos/gifs for anything!

[danemorgan]

I started working on section 3 during WCUS. I did not get very far because, as it turns out, creating documentation seems to be harder than just doing things.

I fully intend to continue working on section three next week after I get home from Nashville.

The start I have lives here

https://docs.google.com/document/d/1oqnZjl6jxg7OkYm93hpMB79s-yKDQULSvxHxP8wMkEA/edit?usp=sharing

[jessestu]

I am drafting Section 4: Common Questions in this Google Doc:

https://docs.google.com/document/d/1ji6dsrP_9Cw_G_E1VWRPVECl7gFGc7Ab_Jvoz-rnBOk/edit?usp=sharing

[CalumChilds]

@danemorgan I've added a few bits to the Spotlight and Full-Screen modes in Section 3. Please let me know what you think!

[0aveRyan]

Gutenberg User Docs Updates:

• This ticket remains the primary point-of-reference for all work going forward
• Target Dates:
  • Next meeting in #docs is January 15 at 6:00 PM UTC.
  • Rough Draft complete by January 15, end of US business hours. see below
  • Edits & Refinements complete by January 29, end of US business hours.
  • First Edition Launched in HelpHub by February 5 (Jan 31 if possible).
• @chrisvanpatten has asked me to take over day-to-day on getting User Docs to the First Edition, but will still hopefully be available during edits and refinement.
• Originally our goal was to have a rough draft sooner, but as WP5 released we’ve received additional materials and interest in working on these docs. We also had long-standing holiday plans. We’re back in action now.
• CLEAN OUTLINE: https://docs.google.com/document/d/1L7WdbKw6Mwos5jkcWJD8yZnhHJDXvrskxU3K_FxosVM/edit
• ROUGH OUTLINE: https://docs.google.com/document/d/1a-Ohg2i70waC2-fN36QlpBXd_olHtZ3WJ3XKq8pxzU4/edit
• ROUGH DRAFT: Coming next week
• DESIGN ASSETS: The #design team has kindly offered to contribute some labeled diagrams. Our main goal is to clarify all the nomenclature and provide a visual reference for sighted users for shared names. This is a rough list, and not all necessarily need to be done for the 1st Edition of User Docs to launch, but main goal is to surface some of the contextual states in the editor and provide a visual reference for the Terms Glossary. These could be wireframes, labeled screenshots, GIFs/MP4s of interactions, etc.
  • General, High-Level UI Overview
  • Top Toolbar Overview
  • Main Menu Overview
  • Sidebar Overview (Document/Block)
  • Block Toolbar Overview (perhaps with Paragraph as its default)
  • Pre/Post Publish Panels
  • Block Inserter
  • Slash Inserter
  • Using Custom Plugins

If you're interested in getting involved or have additional materials already created you'd like to contribute, please paste links here no later than January 20 and reference the outline documents for what is already written/covered. Please ping me in the #docs channel @dryanpress with any questions or tag me on this issue (@0aveRyan).

[0aveRyan]

Punting rough draft delivery ETA until January 16 at 5PM UTC to account for some unexpected, urgent demands on my time outside work. I will still be in today's #docs meeting.

[joedolson]

Is there anything I or the Accessibility Team can do to help move these forward?

[andreamiddleton]

What's the status of this effort, given the work done recently on Block Editor Docs? I see there are now user-facing docs here:

• https://wordpress.org/support/article/wordpress-editor/
• https://wordpress.org/support/article/blocks/

[joedolson]

I'm particularly wanting to know whether the documentation incorporates the hard work put in on providing information for users of assistive technology - I'm not seeing that information reflected in the Block Editor docs that have been published.

[oandregal]

Is this still relevant now that the handbook has been reorganized and migrated to https://developer.wordpress.org/block-editor/ ?

[gziolo]

@karmatosed can we close this issue? You mentioned yesterday during Core Editor chat that those docs exist.

[karmatosed]

Yes this issue can now close, thanks for closing loop.