Re: [site] DwA and related documentation

[Leo Simons <le...@apache.org>]

Farr, Aaron wrote:
> 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: dev-unsubscribe@avalon.apache.org
For additional commands, e-mail: dev-help@avalon.apache.org