<p>That depends. As a personal rule, I see 3 general levels of documentation:</p>
<p>1. Beginner guide/tutorial<br>
2. Reference Manual<br>
3. Architecture</p>
<p>1. The first type is the one that scratches the surface, gives a few usage examples, and generally helps newcomers and users.</p>
<p>It explains why you'd use the library/module/thing, and directs in how to do so. It holds the user's hands so they can quickly solve whatever problem they have.</p>
<p>The raw version of this is either reading test cases or Open Source code that uses the product.</p>
<p>2. The reference manual is a listing made to help those who already know the item. It details everything but gives few explanations. It can be used to deepen one's knowledge, but won't do any hand holding, or very little.</p>

<p>EDocs and the general javadoc-style stuff fit this well.</p>
<p>The raw version of it is 'read the source, Luke'. It works for experienced users, and is of nearly no use to others.</p>
<p>3. Architecture is the doc that explains why the app was built the way it is, a view of how it works from 10,000 feet. It shows how to understand the app were you to dive in its source.</p>
<p>This kind of doc explains the rationale of some choices made, and is especially helpful to developers or contributors to your code, so that they do not undo future plans, respect trade off decisions you made, and know where to dive in to extend things without causing headaches to anyone.</p>

<p>I know of no raw version of this; it's experience and in-depth knowledge of the product's life. Writing this doc is often vital to raise the quality and relevance of contributions received.</p>
<p>----</p>
<p>In my opinion, you don't have great documentation until you covered the 3 aspects. You can have poor, decent, or good docs without all of them, but greatness requires to cover all bases.</p>
<p>A self-proclaimed complete book, in-depth tutorial, or course, should touch all 3, for example.</p>
<p>Understanding your code well and making it self-explanatory sadly rarely helps with more than one out of 3 points.<br>
</p>
<div class="gmail_quote">On Jun 1, 2012 12:35 PM, "Robert Virding" <<a href="mailto:robert.virding@erlang-solutions.com" target="_blank">robert.virding@erlang-solutions.com</a>> wrote:<br type="attribution">
</div>