[IAEP] Alpha API Docs are up.

[Gary C Martin]

On 10 Jun 2008, at 03:29, Albert Cahalan wrote:

> On Mon, Jun 9, 2008 at 2:28 PM, David Farning <dfarning at gmail.com>  
> wrote:
>> On Mon, 2008-06-09 at 01:51 -0400, Albert Cahalan wrote:
>
>>> Thanks for the effort. Please don't shoot the messenger, but...
>>>
>>> This is not proper API documentation. It's not complete, and not
>>> at all organized. It's also not a good API as far as I can tell.
>>>
>> I have published the files I used to generate the APIs at
>> http://www.sugarlabs.org/gitweb/pub
>>
>> The APIs are generated from docstrings in the original code which is
>> available at http://dev.laptop.org/browser .
>>
>> Patches welcome.
>
> No reasonable patch could possibly help.
>
> The problem is with the concept. One can not
> generate decent documentation by running code
> through an automated extraction process.
>
> Automation can get you a nice source browser.
> See http://lxr.linux.no/ for an example.
>
> For real documentation, there is no way to avoid
> the writing effort. You need to use the word processor
> of your choice (possibly involving TeX or *roff) and
> just start writing. Documentation isn't easy. :-(

As an activity developer, I am _much_ happier with doc strings. Up to  
now I just run "pydoc -p 8080" on my XO and then point my browser at  
it for all the available docs for whatever build I'm working on.  
Really extremely useful! Especially once you've done the basic poking  
about some of the hello world type examples. Even given the fairly  
thin state of the current doc string material, for developers, doc  
strings are the way to go. So, thanks David, for trying to make the  
latest strings available another way.

Real documentation, as Albert put it, is out of date before it's even  
published, unfortunately. Even if it has a very active writer who's as  
clued up as the core developer team. I'd much rather see more effort  
on an agreed level of doc strings from the core developers, and  
someone keeping an eye on the quality of the example activities to  
make sure they are best case and up-to date. I'm all for well written,  
high level, introductory tutorials to get folks going, but that's a  
very different text to documenting a fast moving system/API.

The documentation case not well covered at the moment is for the lower  
level os stuff, but that's more because it's still so transitory and  
in flux. There's no easy option here, some high level doc strings  
would be nice to get your orientation, but reading and understanding  
the source is really the only way to participate (and I'm certainly  
not there yet) . Unless you have a stack of free time, and already own  
a wizards pointy hat (no insult intended), it'll be very hard to offer  
much more than fairly trivial patches to the core. Many of the lower  
level changes that I'm sure folks would like to help with (or  
replace), just touch too many other areas, it's hard to isolate a work  
task.

--Gary