Sugar API documentation

[Edward Cherlin]

On Mon, May 5, 2008 at 1:40 PM, Bernie Innocenti <bernie at codewiz.org> wrote:
> Edward Cherlin wrote:
...
> > I am a professional API tech writer, and I have been a developer. I
> > would be delighted to work on this, if I could get the support I need.
> > What do the developers use now?
>
>  I talked about it with Marco on IRC.  Some documentation is done with
>  gtk-doc because of our extensive use of the Gnome APIs.  We are not
>  opposed to switch to something else (Doxygen, Epydoc) if there seems
>  to be benefits and someone volunteers to do the conversion.
>
>  Checkout the main Sugar repository and have a look yourself:
>   git clone git://dev.laptop.org/sugar

I'll have some questions tomorrow.

>  There are plenty of other related projects that could use some love.
>
>  Personally, I think documenting these low-level details and the
>  internals of Sugar has a low effort/utility ratio.  The code base
>  seemed sufficiently understandable even the first time I've looked
>  at it.

There are some complaints. Perhaps we can find a low effort way to
gain more utility. I'll take a look soon.

>  There's much more value in clearly describing the overall architecture,
>  the interaction between Sugar and Activities, the various DBus
>  protocols, etc.  Some of this exists in wiki.latop.org, but much of
>  this information is incomplete, disorganized or just bitrotting.

OK. I'll create an Architecture Doc page on the Wiki tomorrow, and put
in an outline of the topics I know about. Pointers to other
information will be needed. Let me know of anything you had a hard
time discovering that still isn't in the Wiki, or is hard to find
there.

>  So, rather than the API-oriented fine-grained documentation (which
>  may be a lot of to revise and extend), I'd like to see the stuff in
>  the wiki reorganized and revised to assume the form of a comprehensive,
>  top-down developer manual for the Sugar environment.

Other wishes should be stated ASAP, because I am going to start designing

a) what I am asked for
b) what I see as needed

I often do what I call Defensive Documentation. I write the manual I
wanted to have in the first place. Occasionally I can get paid to do
this, although usually I get decent source docs from engineers.

>  My non-pro $0.02 opinion.  Edward, what do you think about it?

I thought you would never ask. ^_^

>  --
>   \___/
>   _| o |  Bernie Innocenti - http://www.codewiz.org/
>   \|_X_|  "It's an education project, not a laptop project!"
>



-- 
Edward Cherlin
End Poverty at a Profit by teaching children business
http://www.EarthTreasury.org/
"The best way to predict the future is to invent it."--Alan Kay