-
Notifications
You must be signed in to change notification settings - Fork 10
Stages in the development of layout information
This page gives some advice about how to develop a gap-analysis document and accompanying requirements documents.
The gap-analysis, in particular, is best approached by starting simply and then progressively adding evidence, tests, results, etc. The worst scenario is one where no information is created because there isn't time to make the document perfect. On the other hand, one also needs to beware of deep-ending into one specific area and neglecting others.
The best approach is likely to involve starting with a simple pass over the whole document, then progressively adding detail later.
Here are some suggestions about where to start, and how to carry on.
For examples that illustrates some of the ideas below, but that are still far from complete, see the sections on Emphasis & highlights and Vertical text in the Japanese gap-analysis document.
Start with the gap analysis document and go through it, looking for obvious things that cause difficulties for users every day. Write a few sentences in each relevant section to describe those issues.
Do not attempt to describe the requirements. Simply describe what difficulties users experience. For example, the section about initial letter styling may contain a statement to the effect that when trying to create drop caps it isn't possible to correctly select the initial syllable in Devanagari text when it contains multiple consonants. It may also say that the alignment points for an enlarged initial syllable are incorrect.
Initially these may just be assertions, but as we develop the material later we will put detail around those statements.
Also add labels for items that are not applicable and that do not cause problems for the user.
It's quite ok to add comments to a section which you have marked as OK or not-applicable. For example, there may be aspects of the writing system that are not really important for Web users, and you may want to mention that you are intentionally ignoring those.
It's better to show evidence of issues, rather than just make assertions.
A simple method is to include a picture or screen snap illustrating the problem.
A better method is to create a test that people can run to see the problem, and link to the test(s) from the appropriate section in the gap-analysis document. We are in the process of developing a number of test formats, ranging from simple adhoc files to a series of formal test formats for use in the Internationalization and Web Platform Tests test suites. More information on that soon.
Test files should test just one specific issue at a time, should state what it is that they are testing, and tell the user how to tell whether or not the test passes.
Tests are especially useful if they can also be used to test fixes that have been applied to browsers.
When providing evidence, either via images or tests, you should summarise the evidence in the gap-analysis document, and include information about what browsers, platforms, devices, etc experience the problem.
Note that the Internationalization WG already has many tests which may be relevant. In addition to the tests themselves, there are pages showing results for major browsers. If one or more tests fit the bill, then link to the test results page from the gap-analysis document. For example, there is a test results page for initial-letter styling in Devanagari text. For a list of all available tests, see the overview page.
While documenting an issue, go and check whether a solution for that issue is already proposed in the CSS, HTML or other spec.
If there is a section in the spec dealing with this issue, link to it.
Point out any issues, shortfall, etc. that you find with the spec text, or if the spec text would address the issue adequately, say so. This makes it clear where the work needs to be done: in the spec or in the browser.
The actual requirements for a feature should be documented in the layout requirements document, and not in the gap-analysis document. They should be documented in a technology-free way, simply describing the expected behaviour of the writing system for the user. This means the document will be evergreen, whereas the gap-analysis document will hopefully become quickly out of date or need regular updates as the shortfalls of the technologies are addressed.
For example, the gap-analysis document may point out that initial-letter styling in CSS is problematic in Hindi (using the Devanagari script) because it doesn't automatically detect the full extent of word-initial syllables if they contain consonant clusters. That document may also show examples of initial-letter identification problems, and link to some tests that allow spec developers or implementers to reproduce the problem.
In order to fix the problem, those spec developers and implementers need to understand how to segment the text properly. This is the information that belongs in the requirements document.
In addition, the gap-analysis document may point out and demonstrate that the alignment of characters in Hindi 'drop caps' is unreliable or incorrect. Then it is the task of the layout requirements document to describe where the attachment points are for these drop caps (given the fact that Hindi characters hang from a baseline, rather than sit on a baseline), how many lines a 'drop cap' should take up in height by default, and any other special requirements for implementing drop caps (for example, it is more common in indic scripts to enclose the drop cap in a box than it is in English text – how should that look?).
In the end, it should be possible to read the requirements document on its own, and to use it as a source for information by various different technologies. The gap-analysis document (or possibly documents, if several technologies are addressed) should simple list the issues experience by users, and point the reader to the requirements doc for detailed information about how things should work.
A requirements document typically needs a brief overview of how the script works, in the first section after the introduction. If possible, try to keep this simple and avoid adding requirements to this section.
Subsequent sections then describe the expected behaviour of the script in the areas that matter. The initial material may be driven by the results of the gap analysis. The first sections to be written may be those for which there are the most serious user issues.
A requirements document may also contain a glossary and a list of characters needed for writing the language in question. Try not to allow the time spent on such parts of the document to prevent work on the real meat, which is the descriptive text that supports the understanding and requirements related to the user issues.
As time goes by, we would hope that some of the issues raised by the gap-analysis document would be fixed. It would be useful to update the gap-analysis document at such points to make it clear what the current situation is.
It may also be that new issues surface, and those should be added to the gap-analysis document, too.
(As we mentioned before, the requirements documents shouldn't need much in the way of updates, although information about new features may be added from time to time.)