A clean piece of documentation will communicate the underlying concept of the software. It'll do this by explaining what the software's purpose is in a way that allows potential users to see how they might make use of it. This can be considered the educational part of documentation: setting out the terminology and paradigms that will allow the reader to easily comprehend the other parts of the documentation and the software it describes.
To properly express the concepts of a piece of software, it's necessary to step inside the shoes of your users, seeing things from their perspective and communicating with them on their terms:
- Determine your audience: Who are they and what's their general technical proficiency?
- Determine their understanding ...
