* 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
