On Mon, May 5, 2008 at 1:40 PM, Bernie Innocenti <[EMAIL PROTECTED]> 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 _______________________________________________ Devel mailing list [email protected] http://lists.laptop.org/listinfo/devel
