LisbonDocumentationDiscussion

Discussion II: Strategies for documentation of grammars and tools

FrancisBond presented a brief introduction and a related work that is in progress in NTT (TheSlides). After that, the participants discussed how to document, how to motivate people to write documents, among others.

Introduction

• It is hard to keep track of grammars and tools that are being developed by DELPH-IN members all over the world.
• So we are using the DELPH-IN wikis and mailing-lists, but these are still incomplete.
• We need documentations.

An Attempt in NTT

• Lexical Type Documentation for the Japanese grammar, JACY
  • In NTT's HINOKI treebanking project, treebankers are not grammar developers nor linguists. They need a comprehensive and detailed documentation, especially for lexical types, to annotate corpora.
• Requirements:
  • Semi-automatic documentation
  • Flexible browsing
  • Visible to members all over the world
• Key ideas:
  • Put every information into Relational Database
  • Browsing it through the Web

Discussion

How to document

• Description on a high level of the linguistic analysis is often scattered in different papers. It is useful to collect electronic versions of as much papers as possible links.
• Granularity of documentation and modes of documentation depends on users, purposes, or what you want to do with it.
• Modes of documentation
  • documentation for "internal" people, technical, in the grammar files, viewable from outside
  • detailed documentation about phenomena, book or papers.
  • very external documentation about installation etc, online
• The grammar could be annotated with examples, typically for the rules and lexical types.
• Documentation process should be automated as much as one can, as the NTT system does.
• Grammar writers should set up multi-language test suites on certain phenomena and differences in the grammars; something like the MRS testsuite for all grammars.
• Top-level documentation has to be done not only for grammars but also for systems.
• The model in which one system is maintained by one developer is frightening. We need documentation to change this situation.
• The Spanish grammar started with documenting each line of implementation, different phenomena with examples, types. So, it is documented by writing the grammar.

How to motivate people to document

• Some things that have been done for one purpose will be used for another purpose. So, the documentation will have to be adapted to the needs.
• Researchers need things that can be inserted into one's CV, and LSA counts electronic documentations as publications, and so does W3C. This can motivate people to write documents.
• A reason for documentation is also to keep track for oneselves, another is to keep track of Matrix adaptations, to support the Matrix development.
• Interests for documentation it to set up a standard, discussion in the community, comparability of the grammars (how do we want to compare?)

Question

• High-level documentation can be published. low-level documentation, navigation, like the lexical type documentation is very useful, on what scale will we need it?