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

If my other idea seems OK after a little experiment we should 
definitely do that.

Steve

Steve

On 06/02/2020 17:45, lisa.seeman wrote:
> Steve, if you have a process that you think will be useable for 
> everyone, that you want us to try, we can schedule  I can ask the 
> members if they can use it, and we can try it out. That way we can be 
> sure it is usable.
> 
> All the best
> 
> Lisa Seeman
> 
> LinkedIn <http://il.linkedin.com/in/lisaseeman/>, Twitter 
> <https://twitter.com/SeemanLisa>
> 
> 
> 
> 
> ---- On Thu, 06 Feb 2020 16:16:46 +0200 *Steve Lee <stevelee@w3.org>* 
> wrote ----
> 
>     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>
>      > <mailto: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 Friday, 7 February 2020 10:49:39 UTC