Making the gap-analysis docs editable from GH issues

We are experimenting with a new approach for creating content for the 
gap-analysis work.

I will begin converting the template for the iip gap-analysis documents 
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 documents at https://w3c.github.io/sealreq/gap-analysis/beng-gap etc 
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 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 iip repository. Apologies in advance for that.

ri

Received on Tuesday, 4 February 2020 17:39:10 UTC