Re: Thoughts on editorial workflow that's easier to use

On 06/02/2020 13:40, lisa.seeman wrote:
> My initial review is that the pro's and cons do not real get the issue 
> from a coga perspective.
> 
> For exmple,
> "/Formatting requires entering markdown - but people who don't like it 
> can add requests in the issue comments./ "
> 
> This would be fro a COGA perspective:
> 
> /"Formatting requires entering markdown or add issues - but many coga 
> task force users can not use it and do not know how to add issues so 
> they will no longer be able to participate and contribute" // > /

I should have explained that is the 'native format and the issue editor 
has basic WYSIWYG facilities so they are not needed. However, they are 
nowhere near as comprehensive as Google Docs - but that could even be a 
good thing :)

If it was to work at I'd expect we would create issues as part of the 
document structure setup - with one issue per topic (eg pattern). The 
task force would then just work on an issues - rather like splitting our 
google docs up into more managable chunks.

> Over all I think this will be a lot easier by phone,

OK

> but we dont want a 
> process that means we can not get the participation we desperately need.

+1000

It looks like we're still looking for a better solution but I do think 
exploring helps us refine our requirements.

Steve

> 
> All the best
> 
> Lisa Seeman
> 
> LinkedIn <http://il.linkedin.com/in/lisaseeman/>, Twitter 
> <https://twitter.com/SeemanLisa>
> 
> 
> 
> 
> ---- On Tue, 04 Feb 2020 14:11:51 +0200 *Steve Lee <stevelee@w3.org 
> <mailto:stevelee@w3.org>>* wrote ----
> 
>     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 Thursday, 6 February 2020 14:16:52 UTC