[Its.an.education.project] An "About" statement?

[Steve Holton]

On Mon, May 5, 2008 at 1:00 PM, Greg DeKoenigsberg <gdk at redhat.com> wrote:

> It has seemed, from my (increasingly distant) perspective, that the APIs
> have never really been stable enough to merit documentation -- any effort
> in documenting code today would be useless in three months.  If that's
> changed, that would be great.
>
> And when I say "documentation", I mean "a handful of awesome activities
> that are copiously documented in a literate programming style."
>
> But if any part of the API is unstable -- like, for instance, the activity
> sharing API -- then *all* of the focus needs to be on shoring that part
> up.  Personally, I don't think that activities are all that interesting
> until every single one of them can be shared in at least some small but
> meaningful way.


To my mind, you're saying the same thing twice.

I reject the view that *documentation* has a *stable-API* dependency.
Rather, *documentation* has a *stable API requirements* dependency. Clearly
*stable-**API a*lso has a *stable API requirements* dependency as well.

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.

-- 
Steve Holton
sph0lt0n at gmail.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.lo-res.org/pipermail/its.an.education.project/attachments/20080505/acb2a768/attachment.htm