[Its.an.education.project] Sugar API documentation
Edward Cherlin
echerlin at gmail.com
Tue May 6 11:14:38 CEST 2008
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
More information about the Its.an.education.project
mailing list