Hints to better docs

[Berin Loritsch <bl...@d-haven.org>]

These are just some observations that I have collected or been taught 
over time.  I have trained new users with Avalon, and I had a brief 
stint where I could have had a book published.  In retrospect, it is 
probably a good thing the book never did get published--at the time 
there was far more volatility here than now.

* If the user doesn't need to know, don't mention it.  If you mention
   something, the user will want to know about it.  The more you mention,
   the more the user feels like they have to know to really use it right.

* SoC.  Separate out the concerns for the documentation so that you can
   focus on one thing alone.  Telling a user how to build a project is
   separate from how to develop components.  It might be useful
   information, but supply it as a link.  Wikis are good at encouraging
   you to do it.

* KISS.  Only show what is important at the time.  If the user wants to
   learn about how to find other components, don't include code that
   demonstrates how to get a logger.  The user is smart enough to put the
   two together as or when they need to.

* Be sure of your audience.  If you are targeting a user, don't include
   terminology that hints at an implementation.  That is for a developer.
   Don't forget your developer, he needs to know the high-level ideas
   that influenced the current design.  You don't need a detailed spec
   sheet, just communicate the thought processes.

Every person I tried to give the full picture to right off the bat, 
wanted to know more than they needed to.  It is best to give them enough 
to work on for the time being, and when they need more help you give 
them just a little bit more.


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