On Mon, May 5, 2008 at 1:00 PM, Greg DeKoenigsberg <<a href="mailto:gdk@redhat.com">gdk@redhat.com</a>> 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. If that's<br>
changed, that would be great.<br>
<br>
And when I say "documentation", I mean "a handful of awesome activities<br>
that are copiously documented in a literate programming style."<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. Personally, I don'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'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'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? When you do that, your documentation doesn'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>