Documentation Roadmap
From Olympus
Contents |
Overall Aims
Antoine thinks two types of documentation are sorely needed:
- instructions on how to plug-in your own ASR, TTS, NLU, NLG. This means a clear description of the Galaxy input/output but also a description of the code of Kalliope, AudioServer, and SphinxEngine (or whatever the new audio input components Udhay is working on are called). At the very least, people should be able to write their own SynthesisManager for Kalliope (to interface with their preferred engine) and their own SphinxEngine-like program (from the requests we got so far ASR is the component most people want to change).
- a good tutorial for RavenClaw. RoomLine is a good example of what a complete system might look like but it's way too complicated for people to learn RavenClaw. So we could keep the RoomLine task and base a tutorial on a toyish version of it (even better, the tutorial should start from a toy version and progressively add elements ultimately leading to the current RoomLine system). I think people need to learn:
- the basic RavenClaw syntax (how to describe the agent tree and declare and use concepts)
- the grounding/error handling mechanism (first based on hand-written heuristics, like Let's Go)
- how to build models for confidence annotation and error handling
Current status of documentation
Wiki
The wiki's overall organization is probably ok. The main page starts with links to existing systems, documentation, download, and some development links. Going one level down into any of the documentation or development links in general leads to an out-of-date and unorganized note. Essentially these need to be revamped. There are also a lot of missing links where stubs or something better could be put in.
ravenclaw-olympus.org
This site looks a little better than the wiki and does a better and more coherent job of explaining what olympus is. There's a single documentation page. It's coherent and concise, but mostly is an installation guide. Also, there's a lot of duplication between the wiki and this site.
RavenClawDoc.doc
This doc is a work-in-progress, or perhaps an abandoned work-in-progress. It's mostly an outline. Again there is a lot of duplication with the web page and the wiki.
Proposals for Action Items
My suggestion would be to focus efforts on the wiki since it's the more easily extended and edited than any of the other formats. We can improve it's look and feel and overall architecture, perhaps modeling after the ravenclaw-olympus.org page, and also incorporate the content of some of those pages. TK 10:31, 3 August 2007 (EDT)
