Thoughts on editorial workflow that's easier to use

I've been thinking about how we might better support taskforce editorial 
work on our documents.

Currently, due to the requirements of Taskforce members, we do not 
follow the common GitHub based workflow for content development.

Rather, the majority of our work is carried out in Google Docs and an 
"editor" then performs the typical GitHub Pull Request, Review and 
Commit to make the preview document available. Eventually, Roy and 
Michael do the final magic to publish the document for review etc.

In today's W3C team EU meeting Richard Ishida from the 
internationalisation task force mentioned an approach he is exploring. I 
think this could potentially replace our Google docs use. These are 
known to have accessibility issues and locating documents can be a 
problem due to them all living somewhere in "G-Space".


# Overview

Richard's process uses GitHub issues to contain the content that is 
visible in a version of the full document when viewed in a browser. When 
the issue is updated the latest content can be seen immediately in the 
browser (perhaps after a refresh).

There is no build process.

A GitHub issue contains the text for a single block of content that 
appears in the HTML document as follows:

* The issue number is used as a link to the issue in Github

* The issue title is used as a header for the block.

* The 1st comment in the issue is the text that appears in the document 
block.

Anyone with permissions can edit the text in the issue.

Other comments in the issue are used for Task Force discussion or 
requests for changes to be made.

Here is an example - the text in the section "#171 Table cells don't 
handle vertical direction properly" is taken from the github issue 171

https://w3c.github.io/jlreq/gap-analysis/#issue171

https://github.com/w3c/jlreq/issues/171


# Details

As I see it, when the taskforce collaborative work is complete and an 
issue is ready to be closed the text from the 1st comment will be merged 
into the GitHub repository, Just as we currently do with Google docs source.

Technically this works with a script added to the template document 
source. The latest version of the document is always available at a URL, 
for example using GitHub pages at github.io).

Note W3C working documents already use scripts (respec) so this is 
nothing new and fits with existing W3C publishing processes.

This script looks in the template document for a markup "label" that 
identifies the bloc and then use the GitHub API to find an issue with a 
label containing the same name. It then grabs the issue text and formats 
it into html for display.

Additional process can be overlaid as required but I think it's best to 
keep it simple.

To make it work editors with HTML skills need to maintain the structure 
in the document template.

So here's some pros and cons compared to the current Google docs approach

Pros:

* All discussion stays with the document source in the repository, not 
lost in 'G-space'
* Easy to locate any section being worked on by searching the issues
* Issue labels help organise issues - also potential to use GitHub 
Projects and Milestones for more organisation
* Source content is just text (markdown) so is easy to process via 
javascript and API
* Share scripts and process with i13n task force and possibly others

Cons:
* Formatting requires entering markdown - but people who don't like it 
can add requests in the issue comments.
* Possibly best for text blocks with other structure maintained in template.
* Markdown tables are likely to be fiddly
* Could be slow for complex docs as processing is at runtime rather than 
build time.
* Requires GitHub API to be available - but they have excellent service 
levels

Note: While google docs offer real-time collaborative editing we 
actually find this a pain as the text on the screen jumps around.

I think we could use W3C html diffs which is probably better for the 
Task force than other options. Needs a simple way to invoke it - perhaps 
a link in the document.

Comments please?

I propose I work with Richard to set up an experiment for the cognitive 
taskforce.

Received on Tuesday, 4 February 2020 12:11:55 UTC