[site] DwA and related documentation

["Farr, Aaron" <Aa...@am.sony.com>]

Hello.

I've been very pleased with how quickly the site updates are progressing.
In fact, I can barely keep up!  I'm looking forward to continuing to improve
the documentation on all our projects, but specifically I'd like to look at
our core articles.

The way I see it, our core documentation is made up of:

    Developing with Avalon
    The Framework docs on Component Programming and Lifecycle
    The Phoenix Guides
    The Merlin Getting Started Docs

These represent some of our most well written pieces, but some are out of
date and together they don't quite give a complete or consistent view of
Avalon.  My 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

Now, some of this may overlap.  For example, perhaps we want to have the
Developing with Avalon paper focus on Merlin and mesh with the Merlin
tutorial(s) while the Getting Started Guide would complement Fortress.  I'm
just through ideas out here, but it would be nice to have a general plan of
attack.


J. Aaron Farr
  SONY ELECTRONICS
  DDP-CIM
  (724) 696-7653



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@avalon.apache.org
For additional commands, e-mail: dev-help@avalon.apache.org

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