Talk:Documentation Team
One programmer's opinion:
I believe it is a mistake to rely on "read the code" as a solution to sugar documentation. There needs to be a document for each class this organization invents. The document should contain at least the following:
1. What the class is for and when it's appropriate for the developer to use it.
2. What the class is derived from (if anything), what base-class methods/attributes it overrides/extends/hides and what new methods/attributes are provided. *
3. Methods and attributes reference (it could be appropriate for this part to be generated from the code).
(*) Pardon me if that's not Python-speak: I'm new to the Python language. Methods are the things in a class that start with "def"; attributes are the class's data.
Finally, there needs to be both an index to classes and a "roadmap" showing how the classes relate to each other. Examples would be nice to have, too, but this "developers' reference guide" is essential -- otherwise the learning curve is too steep and third-party developers will go devote their time to some easier-understood project.
I hate to hold Microsoft up as a good example (they aren't -- they're only so-so when it comes to documentation), but the hyperlinked documentation for the Microsoft Foundation Class library is fairly decent. The documentation for the Swing library in Java is nearly as good, though the class library reference part could use a better layout.
A nice-to-have in all of this would be the ability to call up the relevent documentation while coding, as can be done in Visual Studio. dave 20:03, 19 May 2008 (UTC)
- sugar-base and sugar-toolkit has API documentation in the code. What tool do we use to generate html? Where do we generate it and where we make it available? Do we need to build them to generate docs?
- See http://wiki.laptop.org/go/API_reference#System_Services.2FHardware for PyDoc and epydoc references. Also, how do we want to reference http://wiki.laptop.org/go/API_reference? Is it out of date? Do we start from scratch, or just update that? --Morgs 14:57, 30 May 2008 (UTC)
- Probably we should document the datastore dbus API. I'm not sure what's the best way to generate documentation for it. It's so small that a wiki page might be the simpler solution for now.
- Collaboration API. I have no idea, morgs we need your help here.
-
- Morgs, my impression after a 3 minutes look over the available documentation is that there is little written with activity authors in mind, and that it's dispersed in several pages and mixed with implementation docs. Is that impression correct? I would like to have a couple of things: 1 complete documentation of the API which interest activity authors (with good links to dbus documentation since it's used so heavily) 2 A complete tutorial as part of the "manual". One of the Tubes pages looks like a pretty good start in this respect. Does it make sense to you? Can we make it happen? -- Marcopg
- Yes we can! --Morgs 13:50, 16 May 2008 (UTC)
- Hey, I came up with an alternate "reference" implementation for collaboration when I wrote Colors!, I think it's a lot easier to understand and could be the basis for a good tutorial. The only weird thing is, I wanted my activity class to receive DBus signals directly, so I subclassed ExportedGObject but initialized late - hacky, I know. It would be nice if this were not needed! [2] Wade 18:49, 18 May 2008 (UTC)
- Low level API (non-python activities). We should just move bert document on this wiki.
- this is the page http://wiki.laptop.org/go/Low-level_Activity_API but it must be complemented with
Manual
- Setup a development environment. This is wiki oriented so we should probably not even mention jhbuild (we should definitely not do so until we have a bunch of autobuild slaves running).
- "Write your activity" tutorial. It should include all the important bits: graphic controls, datastore, collaboration
- see OLPC Austria's Activity Handbook ChristophD 03:59, 30 May 2008 (UTC)
- Probably good to have a pygame tutorial, it's probably the best thing we have at the moment to do free form graphics stuff.
- Etoys based activity tutorial?