Converting gap-analysis doc to work with issues

After talking with Kida-san and others, we decided to experiment with a 
new approach for creating content for the gap-analysis work.

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/alreq/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 try to add more code for that. 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 Atsushi, 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 jlreq repository. Apologies in advance for that.

ri

Received on Monday, 3 February 2020 11:47:49 UTC