wish list of documentation looks like:
Getting Started Guide : a new users guide with tutorial
Developing with Avalon : the more advanced developers guide
Thorough tutorials for both Merlin and Fortress A well maintained Avalon FAQ (in wiki)
A well maintained Avalon Glossary (in wiki)
Avalon in Action Paper : compares avalon to other systems
Looks at embedding avalon
Include the current AvalonYouMakeTheDecision
* normative-style reference (ie some of the stuff we have in /framework/)
it would be nice to have a general plan of attack.
word of caution: writing big pieces of comprehensive documentation is very challenging; so is maintaining them. Various people have repeatedly failed at maintaining "comprehensive" documentation on stuff, here, and elsewhere. I think Steve, with the merlin tutorials, figured out how to do it nicely: write small, relatively disjoint "howto"s or essays, then link those together (using navigation.xml, mostly :D) into something with a bit more unity.
That way, when you have an itch to document something, you can scratch it in an hour.
Having said that, writing a big piece of well-written software manual is a bigger challenge, and hence may be more fun to do. Just make sure you're able to complete what you started; that's always been a problem for me :D
cheers,
- Leo
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
