Mini Doc Sprint Report

TL;DR: A belated report on the results of a Google-sponsored mini doc
sprint in Tokyo last week.

Goals:

   - Fix content bugs
   - Refine content creation and editing workflows
   - Train participants so they can teach/lead others
   - Develop tools and processes for wider, community-attended doc sprints
   - Test notions about 5-minute, 30-minute, and half-day tasks
   - Improve the usability of the templates and forms
   - Develop solutions for compatibility tables

Summary:

Members of the Google Chrome Developer Relations team and other Googlers
got together in Tokyo last week for an afternoon to focus on WPD, it's
content, architecture, and the tools and processes needed on the site. One
of our original goals was to train ourselves so that we could teach and
lead others in subsequent doc sprints, and we developed tools and processes
to support this. We also wanted to test the notions in place around
completing the tasks described in the Getting Started
page<http://docs.webplatform.org/wiki/WPD:Getting_Started>.
Within that also, we were intent on improving the workflow - and the
instructional pages for this - while making improvements to the content.
Another goal was to use the talent on hand to improve the templates and
forms and explore solutions for automating some of the content development
like the compatibility tables. In only a few hours we made a lot of
head-way. Our results are summarized below. Many of these issues are or
will be dealt with in subsequent posts to this list.

*Developing doc sprint tools and processes*

We started experimenting with a Doc Sprint Task Tracker<http://goo.gl/aHbcP> (a
Google Docs spreadsheet) to develop a way to track progress and metrics for
doc sprints. The idea is to give participants a "to-do" list that
simultaneously segregates tasks by work area (so people aren't stepping on
each other), tracks task progress, and provides metrics around how many
pages edited and how much time taken. Note, the spreadsheet as is does not
reflect reality - we didn't follow through on the status or metrics on any
of the tasks (we ran out of time).

This weekend's doc sprint in San
Francisco<http://www.sfhtml5.org/events/87609752/>will be another
opportunity to put the Task Tracker through its paces.
Let's see what improvements come of that.

*Moving pages*

We discovered some gotchas with respect to moving pages. See separate
thread, “Guide on the dangers of moving pages?” by Alex Komoroske, October
25, 2012

*Using w3.org content*

Questions came up about using content from specs published on w3.org. See
separate thread, “Using W3C spec text on WPD” by Alex Komoroske, October
25, 2012

*Compatablility table bugs found*

We found some bugs in the compatibility tables; see
https://www.w3.org/Bugs/Public/show_bug.cgi?id=19700

*Improving templates*

Alex Komoroske brushed up some of the templates to make them easier to use.
We'll continue to refine the templates as we work through the process for
creating new content (see below).

*Creating new pages workflow*

We identified a need to guide contributors when creating new content. While
developing the documentation for WebRTC, Scott Rowe (with help from Alex
Komoroske) is concurrently recording the steps for creating new content -
stubbing out the articles, which templates to use, how to use the
architecture (see below), and all that goes into building out a new content
area. Scott Rowe will update the Getting Started page and related articles.

*Using the architecture*

There are some significant differences between the architecture we have
prescribed and the architecture we actually have. These and greater clarity
about how to use the architecture when adding new content need to be
spelled out in the Architecture
page<http://docs.webplatform.org/wiki/WPD:Architecture>.
Scott Rowe has taken the action item to update the Architecture page.

*Auto-filling compat tables*

Paul Lewis started working on a MediaWiki plugin to pull in, cache and then
serve up the data from caniuse.com for the compatibility tables. See the
separate thread, "Compatibility Table Plugin" by Paul Lewis, October 25,
2012. Basically, the idea is to inject the data on a one-time basis so that
the compatibility tables are still editable. This is just in the
investigation stage at this point, and there are a lot of issues to resolve
around it - as discussed in the Tuesday morning teleconference this week.
Stay tuned.

*Injecting content with a script*

Related to Paul Lewis' work, Boris Smus started developing a script that
uses a MediaWiki API to inject content into pages. The immediate purpose of
this was to achieve the one-time injection of content for the compatibility
tables, but there may be myriad other uses.
https://github.com/borismus/webplatform-tools.

*Content fixes*

Although we didn't do a great job of tracking metrics, our experience was
that tasks took longer than 5 minutes, 30 minutes, etc. We may need to
recalibrate. Below are some of the content areas the team worked on:

   - AppCache
   - File API
   - WebRTC
   - CSS calc function
   - Getting Started page
   - HTML Attributes - used copy-n-paste of raw markup for each of HTML3,
   4, 5 compatibility

*Translation*

Also while we were in Tokyo, at a well-attended HTML5 User Group meeting,
we heard loud and clear that the Japanese developer community is eager for
the translation infrastructure to be in place. Yes, pressure!

Thanks to everyone who helped out!

+Scott