|
| 1 | +# How to contribute to a gap-analysis document |
| 2 | + |
| 3 | +Practical steps for editing the document gap-analysis/index.html |
| 4 | + |
| 5 | +## Describing a gap |
| 6 | + |
| 7 | +Try to keep the structure (sections, headings, etc) intact, since we rely on them to run batch processes and link from various places. If needed, we can add a new section, but it should be done in collaboration with Richard Ishida. Note that there are catch-all sections available at the end of each division which can be used for things that don't appear to fit elsewhere. |
| 8 | + |
| 9 | +The basic structure of a section in the template looks like this: |
| 10 | + |
| 11 | +```html |
| 12 | +<section id="emphasis" class="tbd"> |
| 13 | + <h3>Emphasis & highlights</h3> |
| 14 | + <p class="status_prompt">Bold and italic are not always appropriate for expressing emphasis, and some scripts have their own unique ways of doing it, that are not in the Western tradition at all. Does this script require support for emphasising or highlighting text that cannot be achieved currently? <a href="https://w3c.github.io/typography/index#emphasis">See available information</a> or <a href="https://github.com/w3c/i18n-activity/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Aemphasis%20label%3Atype-info-request">check for currently needed data</a>.</p> |
| 15 | + |
| 16 | + |
| 17 | + <p></p> |
| 18 | +</section> |
| 19 | +``` |
| 20 | + |
| 21 | +The paragraph 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. |
| 22 | + |
| 23 | +The `<p></p>` markup at the end of the section can be replaced with any HTML markup you like. You can have several paragraphs, lists, or even create level 4 (`h4`) headings. If you do that, however, you should surround the h4 heading and it's content with a `<section>` tag, so that respec works nicely. You should also add an id to the section tag, so that people can link directly to that subsection. |
| 24 | + |
| 25 | +You can see an example of a filled in section for Japanese at https://w3c.github.io/jlreq/gap-analysis/index.html#emphasis |
| 26 | + |
| 27 | +The content of a subsection should eventually contain information about what doesn't work, with the following details: |
| 28 | +1. how the feature is broken for users (ie. what can't they do) |
| 29 | +2. links to tests (or sometimes inline markup) or screen snaps that show the feature failing |
| 30 | +3. a description of which applications (eg. browsers with versions) support and don't support the feature |
| 31 | +4. pointers to the CSS or other W3C specs that relate to this feature, with descriptions of whether the gap is addressed or not |
| 32 | +5. links to the detailed description of requirements in the lreq doc |
| 33 | + |
| 34 | +Don't go into too much detail about how a particular feature is expected to work here – that's what the lreq document is for. The two documents are intended to support each other, not duplicate content. |
| 35 | + |
| 36 | +If describing gaps for more than one language, and there is a difference in the level of support, make it clear which language is relevant to the text. |
| 37 | + |
| 38 | +## Adding a priority |
| 39 | + |
| 40 | +Having described the gaps, you need to assign a priority to this section. To do this, add a class name to the section tag. In the template example above, replace the `tbd` with one of the following: |
| 41 | +* `ok` |
| 42 | +* `na` (not applicable) |
| 43 | +* `advanced` (needs work for advanced level support) |
| 44 | +* `basic` (needs work for basic styling support) |
| 45 | +* `broken` (basic display issues that prevent effective use of this language on the Web) |
| 46 | + |
| 47 | +The class tag will affect the colour of the block alongside the section, and add some summary text at the end of the section. |
| 48 | + |
| 49 | +Note that this priority labelling is NOT about how badly broken the feature is – it's about how the lack of the feature affects the use of the Web in this language. |
| 50 | + |
| 51 | +Basic styling is the level that would be generally accepted as sufficient for most Web pages. Advanced level support would include additional features one might expect to include in ebooks or other advanced typographic formats. There may be features of a script or language that are not supported on the Web, but that are not generally regarded as necessary (usually archaic or obscure features). In this case, the feature can be described here, but the status should be marked as OK. |
| 52 | + |
| 53 | +The decision as to what priority level is assigned to a described gap is down to the experts doing the gap analysis. It may not always be straightforward to decide. If a given section in this document refers to more than one feature that is broken, each with different impacts on Web users, the priority for the section should be the lowest denominator. |
| 54 | + |
| 55 | +A cell can be scored as OK if the feature in question is specified in an appropriate specification, and is supported by user agents. A specification that is in CR or later and has two implementations in 'major' browsers will count. This means that the feature may not be supported in all browsers yet. (At some point in the future we may try to distinguish, visually, whether support is available in a specification but still pending in major browsers or applications.) On the other hand, you may feel it's important to have more than two major browsers supporting the feature, in which case you can assign a problem status. |
| 56 | + |
| 57 | +If a section is given a class of `ok` or `na` you can leave the description blank, or you can add explanatory text. Whatever you prefer. |
| 58 | + |
| 59 | + |
0 commit comments