Documenting language gaps

The HTML template

A standard template is used for the gap-analysis documents of all groups. It is an HTML document. See, for example, the Bengali gap-analysis document.

The first 3 levels of headings in a gap-analysis document are fixed. They conform to a standardised set of categories that are used throughout the language enablement framework. This makes tooling work, simplifies links, and provides a useful harmonisation of approach across all the groups working on language enablement.

The paragraph in the HTML document immediately after the section title is intended to give you ideas about what you should write about. It is not an exhaustive list, by any means. You should leave that text in place. The links it contains may give you additional ideas of things to describe here – they link to currently outstanding questions or spec/browser bugs relating to this topic.

GitHub issues

The main content of the document is contained in small topic sections. These are authored in GitHub issues – one issue per topic, in the issue list of the group's repository. Here's an example of an issue.

The content is added to the first comment field in the issue list, and some standard boilerplate text is added to the second. Only the content of the first comment field will appear in the gap-analysis document.

People can create additional comments below the first two to suggest or contribute changes. Changes to the content are made by editing the first comment (those changes can be inspected using the available pulldown in the comment header).

The content of the first comment should closely follow the structure that is suggested when you create a new issue. This includes the following:

1. (intro) how the feature is supposed to work. Point to the requirements document or similar for additional information.
2. The Gap: how the feature is broken for users (ie. what can't they do). This should summarise the results of any tests. Also point to any relevant discussions in the issue list of the repo.
3. Tests & results: links to tests or screen snaps that show the feature failing, and, where useful, a summary of the results of those tests. The summary can be copied from the GH issue that records the test results (ie. the list of browser engine data), if appropriate.
4. Spec status: pointers to the CSS or other W3C specs that relate to this feature, with descriptions of whether a sollution to the gap is mentioned or not.
5. Action taken: links to any browser or other bug reports that have been raised.
6. Outcomes: a description of any fixes or developments.
7. Priority: an explanation of why you assigned the priority you did.

If describing gaps that affect more than one language in the same document, and there is a difference in the level of support, make it clear which language is relevant to the text.

See also the section about what to do when the same gap is relevant to more than one gap-analysis document.

Special features

Images. When an issue is incorporated into the editor's draft some transformations are applied automatically. These generally mean that it is easier for you to type stuff in the issue.

If you want to include an image in your gap report, follow these steps:

1. drag the image into the issue while editing. This will add the image to GH and will show some markdown or some markup.
2. copy the image to the relevant language enablement repo and install it at <gap_analysis_file_location>/images/.
3. set the filename of the image in the /images folder to be the same as the alphanumeric sequence after the final slash in the location indicated by GitHub. It is also a good idea to add the extension (which won't be in the GH issue), especially if this is an SVG file.

You should not point out to an image elsewhere on the Web, because all images need to be located locally when you publish the page.

If your image is represented in the GH issue using HTML markup, you can change the alt and width/height attribute values, and those will be captured in the document. Other attribute values won't be.

Headings As shown in the template, the subheadings inside the issue comment should follow ###. There should always be 3 # signs. The headings will be wrapped in h5 markup in the editor's draft.

GitHub issue labels

Item descriptions in GitHub issues are automatically pulled into the HTML document if the right labels have been applied to that issue. (Refresh the HTML page you should see the change immediately.) Labels are also used for filtering in the gap-analysis pipeline. The required labels are:

1. the label gap. Only issues with this label are parsed for inclusion in the gap-analysis doc.
2. a label beginning with doc: (eg. doc:beng for the Bengali gap-analysis doc). Even if the group has only one gap-analysis doc, such as for the Chinese and Japanese groups, this label should be applied (ie. doc:clreq or doc:jlreq, respectively). There can be more than one of these labels, if the gap applies to more than one gap-analysis document in the same repo.
3. one or more labels beginning with i: (for 'index'). These labels indicate which section(s) the item will be placed in (eg. eg. i:letter_spacing), so there is a defined set of possibilities. It's fine to have more than one such label, if you think the topic is equally applicable to more than one section.
4. a label beginning with p:, to indicate the priority for that issue. Each of these labels has a different colour. The usual possibilities are: p:basic, p:advanced, or, rarely, p:broken. If an issue has been fixed, or the text is describing the fact that there is no problem, you can use the label p:ok.
5. labels to indicate where work is needed to address the issue. These labels all begin with x:. If work is required on a spec, the label will include the short-name for that spec, eg. x:css-text. If a browser bug has been raised, add the name of the browser engine, eg. this will typically be one of x:blink, x:gecko, or x:webkit. If the required fix has been provided, these labels should be removed. That way it is possible to filter the issues in the gap analysis pipeline to see what currently needs attention for a given spec or browser.
6. labels to indicate all the gap-analysis documents to which this issue applies. These labels are also used for the gap-analysis pipeline. Since a gap is reported only once in the pipeline, they give an idea of the extend of the problem where that gap applies to more than one gap-analysis document. The labels begin with x:, followed by a short name for the gap-analysis document (eg. x:beng, x:deva, etc.). There must be at least one of these labels (corresponding to the doc: label(s) that you set).

When the same gap belongs in several documents

In some cases, the same gap is relevant to many languages and can be reported in a number of gap-analysis documents. We try to avoid repeating all the detailed information in more than one place by adopting one of 2 strategies.

In some cases, a problem may have aspects that are slightly different from language to language. In this case you may need to create more than one GitHub issue. If you do, indicate in the title of the issue which language/script this relates to.

If the same gap applies to multiple documents in the same repository (eg. a letter-spacing issue that applies to Bengali, Devanagari, Gujarati, and Tamil documents, which are all stored in the same indic repository) simply record the information once, with language-specific examples if needed, and apply two or more doc: labels.

If the same gap applies to multiple documents across different repositories (eg. incorrect application of quotation marks, which affects most documents regardless of the repo where the gap-analysis documents are stored), then choose one repository where you will create a GitHub issue with all the details about tests, spec and browser support. This is the issue that will be tracked in the gap-analysis pipeline.

In the other repositories create a 'stub issue' with the same title that gives a brief introduction to the problem at hand, and optionally contains examples or tests relevant to the language(s) of that repo, but points the reader to the details you are maintaining in the other repo. To do this, after the introduction you should include something along the lines of:

This issue is described in more detail and tracked here.

with a link to the detailed issue. Here's an example.