On 22-01-2013, at 1:23 AM, Nicolas Cellier <nicolas.cellier.aka.nice at gmail.com> wrote:

> IMO, the fact that code is crystal clear is not a good reason to omit
> documentation.

Agreed - comments =/= documentation.

Documents explain the overall system, the intent, the usage, where it doesn't (yet) meet the desired results, where to get updates and ask questions, points to places to start looking at code to build an understanding of it, offers example usage that actually makes sense (I know, I'm a dreamer!) and overall should allow someone to use the code/package/application without ever feeling like they need to understand every detail of the implementation.

To paraphrase Adele Goldberg - "Without documentation, the code doesn't usefully exist. If the code doesn't exist, why exactly did we pay you for it?"

tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Ubi dubium ibi libertas