This page is a draft proposal (by Steve) and has not been reviewed or agreed on bu the task force. historically we follow W3C process and use google docs before the final version as it is easier to use for our memebers.

Less Technical Editorial Workflow - Geek Week Project

Project proposal by Steve for W3 Geek Week

Members of the Cognitive TF and other less technically inclined folks have usability problems with the w3c editorial workflow. The main reason is the tools and terminology are much too low level. Especially when you just want to work collaboratively on content while following a simple edit/review/rework/publish process. Some of the problems are:

HTML authoring - markup is mixed in with content - WYSIWYG is better. Markdown can be a problem unles WYSIWYG markdown
GitHub web tools are much to cluttered and complex - and CLI probably not at all suitable
GitHub Flow to low level and too much jargon (branches and PRs)
Diffs complex - context diffs seems to be a problem so inline (zebra striped )or side by side (does GitHub now support this?)
more?

So currently the TF use Google docs for collaboration using the comments feature with separate task tracking. But:

Someone has to copy/transform content from and back to to W3C HTML tool chain in GitHub.
Previews of final format of updated content are manually managed.

I'd like to explore using tools that address these issues but still support full Git Flow in GitHub for those who want / need it. something like a Headless GitHub based CMS and other tools like Github App or Actions to enable simplified editoral workflow while still allowing usual W3C editorial process in GutHub.

What are the requirements?

This page documents various process the coga TF uses in addition to the W3 Process for TR documents.

Updating an Editor's Draft TR Note before public release

Before releasing a TR Working Draft Note update (or 1st Working Draft) for public review the TF develops a working document in GitHub. This is available for viewing on GitHub Pages For example Gap Analysis

Here's an outline of the process

Author creates a feature branch to keep work in progress off master branch and page preview
Changes are regularly pushed to GitHub for backup (optional)
When ready for a Review a PR is created in GitHub and a reviewer selected
The branch page can be previewed by pasting the branch URL into https://raw.githack.com/ to create a uncached development link
Once reviewed the PR is merged to master - usually by Lisa
The feature branch is deleted from GitHub
The version Master is available for review at https://w3c.github.io/coga/xxx

Releasing a new Working Draft

Working Drafts are publically released versions of Editor Drafts. They can be found at https://www.w3.org/TR/. Links are provided for both the latest version and specific versions. Links appear in the document to earlier versions and the latest editor draft.

Request a WG review and process any requested changes.
Roy or Michael at W3C publish the document.

Responding to community Issues on GitHub

We sometimes get contact by GitHub Issues in the Cognitive TF [GitHub repository](https://github.com/w3c/coga/issues). If we ever get a Pull Request we can create an issue and follow the same basic process.

Create a placehoder response so originator knows we have seen and will respond
[TBD Add a label]
Send a summary or link to the TF list
Add item to next TF meeting Agenda
Respond to the issue as appropriate and close the issue.