Project: Production of language documentation

Project: Requirements specification of a document

In linguistic terms, a document is a complex sign, and the requirements specification of a document is a characterisation of the function of this sign.

In simple terms, the requirements specification discusses points such as the following:

• What are the objectives, goals for the output of a document production project?
• What is the content (in terms of languages, type of multilingual document like dictionary, manual, translation, automatic translation tools)?
• Who is it for?
• How is it to be used (possible applications)?
• What resources are available?
• Do you need a glossary?

From a linguistic point of view, the requirements specification would consist of an analysis of the functions of the document from any of the following points of view:

• Traditional functional linguistics (e.g. Prague School; Halliday's Systemic Grammar and Functional Semiotics)
• Speech act theory
• Discourse theory
• Traditional text linguistics
• Hypertext theory in modern linguistics

Phases in specifying the requirements:

1. The first part of the requirements specification phase may consist of brainstorming, collection of relevant sources of information, interviews with users;
2. the second part may consist of a systematisation of the requirements specification in terms of relevance, or logical dependencies of various aspects on other aspects.
3. Further parts of the documentation specification may take available resources (books, electronic documents, computational facilities, etc.) into account.

Project: Design of a document

The design phase discusses points such as the following:

1. Document semantics: the contents part of the requirements specification; interpretation of the document in terms of the information it conveys.
2. Document structure:
   • Underlying overall structure (architecture) of the complete document as a hierarchy, several hierarchies, cross-connections between parts, ...
   • Parts of the document, constituents such as Chapters, Sections, ...
   • Dependencies between parts of the document, specific aspects of the overall underlying structure
   • Characterisations of specific parts, including Glossary, Reference, Index, ...
3. Document realisation: layout and rendering as a hypertext
   • How is the document structure mapped into a hypertext structure? In other words, in our context, are sub-sub-sections also mapped into separate files, or is it sufficient to map sections into separate files, with sub-sub-sections of in the same file? In a lexicon, is it sufficient to have one table, or should one assign each entry into a separate file?

Project: Implementation of a document

1. Use the appropriate document styles (Title, Heading 1, Standard, etc.) and define them according to your own purposes
2. Use the appropriate document objects, and define them according to your own purposes (lists, tables)
3. What kinds of media materials (text, audio, graphics, video) will you need?
4. What sources are available for these materials? What format converters will you need?
5. What representation tools (e.g. table formatting tools, text tools, HTML tools), and other programming tools (e.g. Praat scripting, Perl, ...) do you need?
6. Meta-documentation: Describe all phases (requirements, design, implementation).
7. Provide source code and examples of all formats.

Project: Evaluation of a document

The main question in the evaluation of a document is simply - "Is this a good document?" Of course this begs a number of questions. There is no absolute notion of `goodness': a value judgment of this kind can be made on any number of dimensions. A `good mother' is not necessarily a `good cricket player', and vice versa...

There are two related but different dimensions of evaluation:

1. Functional evaluation: Does the hypertext fulfil your requirements specification?
2. Structural evaluation: Is the document correctly implemented? You can check this by generating different formats, e.g. standard Word DOC, HTML, and testing it with different viewing software, e.g. Word, a web browser.

You can find out more about the different aspects and methods of evaluation by checking the handbook:
Gibbon, Dafydd, Inge Mertins, Roger Moore, eds. (2000). Handbook of Multimodal & Spoken Dialogue Systemws: Resources, Terminology & Product Evaluation. Dordrecht: Kluwer Academic Publishers.