Making the gap-analysis doc editable from GH issues

We are experimenting with a new approach for creating content for the 
gap-analysis work. Fuqiao asked me to convert the clreq gap-analysis doc 
too.

I will begin converting the template for the jlreq gap-analysis document 
so that most of the content can be written/edited in github issues. This 
makes editing easier, but also establishes a GH issue thread that can 
bring together discussion, comments, and suggested text for developing 
the text on a given topic.

The document at https://w3c.github.io/clreq/gap-analysis/ will 
automatically retrieve the appropriate content from the GH issues list. 
Changes to the latter will be immediately visible in the document if you 
refresh your browser page.

By reducing the complexity involved in maintaining the document in HTML 
and using the GH pull request process, it is hoped that this will make 
it easier for people to contribute to the document, as well as providing 
a handy list of sections in the issue list when filters are applied.

Here is a brief description of how to work with this:

1. the first comment in the issue is what gets incorporated into the 
document. Any edits made to that comment show up immediately in the 
document. We have yet to clarify who should be able to edit that 
comment, and how.

2. below the initial comment, anyone can discuss the topic and propose 
new text, etc.

3. changes can be viewed using the 'edited' pulldown in the top bar of 
the first comment.

Not all markdown constructs are yet converted to html, since this is 
still in development, but i'll  add more code for that in a short while. 
It already copes with paragraphs -> p tags, link markup, markup for 
images that are dragged and dropped into the GH issue, inline code 
markup, and others. Lists, for now, should be coded using html in the 
issue.  You can use inline html markup in the issue, and it should work 
fine on the conversion.

There may still be some editing of the html document itself, for the 
introduction, or for items marked as ok or not applicable.  Those 
however are minimal and few, and if not done already during the initial 
setup of the document can be done by myself, by Fuqiao, or someone else 
who is fine with working with GitHub.

Let me know if you encounter any problems, or whether i should 
prioritise the development of a particular aspect of the 
markdown-to-html converter.

As we convert the document to the template, you will see a flurry of 
issues added to the clreq repository. Apologies in advance for that.

ri

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