On Mon, May 5, 2008 at 1:00 PM, Greg DeKoenigsberg &lt;<a href="mailto:gdk@redhat.com">gdk@redhat.com</a>&gt; wrote:<br><div class="gmail_quote"><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">

It has seemed, from my (increasingly distant) perspective, that the APIs<br>
have never really been stable enough to merit documentation -- any effort<br>
in documenting code today would be useless in three months. &nbsp;If that&#39;s<br>
changed, that would be great.<br>
<br>
And when I say &quot;documentation&quot;, I mean &quot;a handful of awesome activities<br>
that are copiously documented in a literate programming style.&quot;<br>
<br>
But if any part of the API is unstable -- like, for instance, the activity<br>
sharing API -- then *all* of the focus needs to be on shoring that part<br>
up. &nbsp;Personally, I don&#39;t think that activities are all that interesting<br>
until every single one of them can be shared in at least some small but<br>
meaningful way.</blockquote><div><br>To my mind, you&#39;re saying the same thing twice.<br><br>I reject the view that <b>documentation</b> has a <b>stable-API</b> dependency. Rather, <b>documentation</b> has a <b>stable API requirements</b> dependency. Clearly <b>stable-</b><b>API a</b>lso has a <b>stable API requirements</b> dependency as well.<br>
<br>Shouldn&#39;t the documentation follow a parallel path to the code development, so that the delivered documentation becomes both a guide to the users and a guide to the developers?&nbsp; When you do that, your documentation doesn&#39;t have to be composed of your best coders, or of many coders at all.<br>
<br></div></div>-- <br>Steve Holton<br><a href="mailto:sph0lt0n@gmail.com">sph0lt0n@gmail.com</a>