Ideal Developer Documentation

/!\ This is a historical brainstorming wiki page from 2005. The information on this page is not up to date.

If we had perfect developer documentation, what would it look like?

(See also ../DeveloperGuides)

High Level Documentation

This should help people to create an integrated GNOME certified application. It would mention:

  • Introduction: What is GNOME and what is the GNOME Developer Platform.
  • Create a typical build structure, and maybe refer to this example later.
    • Both a simple example, and a full example with translation, help, libglade, MIME, menu item, etc.
    • This could be referred to throughout, but let's not pretend that every section relevant to the example.
  • Brief generic overview of objects, functions, and signals.
  • Recommended memory management strategy, when using C.
  • Create, use, and install a .glade file, with Glade and libglade.
  • Dynamic widget creation (Show this only after showing libglade)
  • Add the application to the GNOME/Freedesktop menu.
  • Register itself as capable of handing certain file (MIME) types.
  • Register new MIME types, if necessary, and icons for them.
  • List the major widgets and dialogs, saying when they are useful, and how they behave (the major methods and signals).
    • This needs an example for each widget, and a screenshot of that example. (gtkmm's book does this).

    • gtkmm's book groups these into Buttons, Range widgets, Miscellaneous widgets, Dialogs, Container widgets, TreeView, TextView, Menus-and-Toolbars, Drawing Area.

  • Derive a widget class, when using C.
  • Create a custom-drawn widget class (Probably in an appendix).
  • Use gnome-vfs to load and save documents, coping with network/permission problems.
  • Internationalize and translate, mentioning UTF8.
  • Write online Help and install it properly.
  • Implement drag and drop
    • For standard data types, such as URLs, for integration with the Desktop and existing applications.
    • For custom data types, usually between parts of the application itself.
  • Implement copy and paste. See drag and drop.
    • Also, how to implement the standard Copy/Paste/Cut menu items, including context menus.
  • Suggest a document load/save strategy, using libxml.
    • Deal with document format versioning.
  • Using GConf to store preferences, and when not to use it and what to use instead.
  • Awareness of Usability issues.
  • Awareness of Accessibility issues, particularly for custom widgets.
  • When, and how, to use the notification area.
  • Dealing with intensive processing, so the application is responsive and shows progress.
  • Responding to theme changes - icon theme?
  • Implement session management.
  • How to have only a single instance of the application.
  • Inter-application communication: DBus.
  • Awareness of performance problems.
    • User perception.
    • Investigation - profiling.
    • Targetted improvement - efficient code fragments, caching, IO, memory.

Thoughts:

  • This should be in DocBook XML.

    • Non-programming-language specific parts could be in separate included fragments, so they could be reused.
  • It should have links to the reference documentation where appropriate.
  • Even if this shows C to begin with, we should plan to add/link-to explanations/examples of the same items in other programming languages.

  • Examples must compile as part of the documentation's build system, and be inserted automatically into the DocBook - see gtkmm's book.

  • Not-yet-API-stable stuff should be clearly identified.

Existing Sources

(Get permission to take/modify content from these)

Plan

  • Create a table of contents
  • Identify what needs to be written from scratch and what can be adapted.
  • Create a build structure, probably in a completely new cvs module.
  • Write the very high-level stuff first, and the widget-specific stuff later.
    • Basics
    • GNOME integration (MIME, Applications Menu, HIG etc)
    • More GNOME integration (GConf, gnome-vfs, copy/paste, drag and drop)
  • Maintain a file with a table of contents status document.

Reference Documentation

What's missing?

  • Documentation of GTK+ signals - when is it emitted, and what information does it give/get.
    • gtk-doc should maybe hide/clearly-mark the (many) keybinding signals, which should almost never be used.
    • This is very difficult for old signals without the original coders doing this. New signals are well documented.
  • Deprecation: Always say what something is deprecated in favour of.
  • Maybe list API from base classes, clearly marked as such.

    • MurrayCumming: I think this could get huge and confusing very fast. I've tried it in gtkmm and reverted it.

    • SteveFeehan: My original rationale for only mentioning signals/properties and not functions is that the base class name is generally in the function name, making it pretty clear where to look for documentation. But signals/properties are not as easy to track down since there is no naming scheme for them.

Discussion

Please add your ideas here.

  • MikeHearn: Microsoft learned the hard way that programmers often just copy/paste example code. Originally the MSDN examples were stripped down and offered no error handling and often took shortcuts. Once they started finding the same patterns cropping up in buggy applications, policy was changed so example code was more robust. A full example app would be a great start, especially if it was more a template that people were expected to copy from rather than just an example. MatthiasClasen: gtk-demo is intended to be just that.

  • More clear examples for why one would want to use certain APIs and how exactly. For example, what can you do with gtk_tree_view_get_vadjustment()? How to choose values for the GtkAdjustment to do X? (where X is some reasonable example use case.)

  • Annotations - we really need the ability for users to add extra documentation in a very easy way where thy don't have to learn things like DocBook. MonoDoc does this. What often happens is someone needs to find out how to do something. They scrounge documentation from around the net but then the next person needs to do the same for similar problems they are solving. If we had annotations the first person might still have to feel the pain but then they might also feel like annotating the docs for the next person who comes along. Rinse, repeat and you all of a sudden have complete docs with annotations from the users point of view.

    • Duplicate: Selfdocumentation, I mean, implement user comments submitting in the reference documentation web interface, I am a php developer and I really love php documentation and I think is part of its success, when I have a problem with a function I go to the online documentation and in the user comments I encountered several solutions, example codes, recommendations, and so on, see here or here,... and I also contribute back when I do tricky and useful code with a function or to alert of buggy behaviours and workaround for them... I would help to implement this with php and mysql.

    • MurrayCumming: This is the live documentation bounty: http://bugzilla.gnome.org/show_bug.cgi?id=306308

  • ShaunMcCance: The book could be developed in DocBook, in CVS, allowing us to leverage our current toolchain and all the other goodness that comes with it. Whenever we make an official release of the book, we would push a static rendering of it to something like library.gnome.org, assuming that exists. At the same time, we could have a live rendering of the document, built from CVS and pushed to the web automatically as frequently as possible. This rendering would allow users to submit comments on a per-section basis, and would display the comments already posted. Readers of the live version can then make suggestions for improvement without worrying about any markup. Maintainers would then be responsible for reading the comments and implementing their suggestions, cleaning them up and adding markup. When a comment has been addressed, we need to be able to mark it as such so that it no longer appears on the page. This way, comments become sort of a bug list attached directly to the source.

    We really want maintainers to be reviewing changes. This will provide much nicer documentation than just allowing rampant editing by anybody. This system will make it dead simple for readers to submit problems and corrections, while still maintaining a level of editorial control over the documentation. Plus, if it works out well, I can adapt it to all sorts of other documentation. :)

  • Even if examples are in C, explanations should keep in mind that many other languages can be used to write Gnome apps and should be as "high level" as possible. Maybe some links to the docs of libs like pygtk should be useful.

    • ShaunMcCance: This might be crazy talk, but could we use xml2po to "translate" documents to other programming languages?

  • Make documentation available in multiple languages or at least easily translatable and set up infrastructure for translation (I know it's hard enough to get docs written in English, but we're talking about the ideal case here and there most definitively is a language barrier).

    • MurrayCumming: Yes, DocBook with xml2po makes this very possible. We do it already for the release notes.

  • Take a look at Apple's OS X Technology Overview. It's full of goodness.

  • Simple and practical, possibly with "carrots" that motivate the reader to learn more technical stuff.
  • Might make sense to develop a small application throughout the tutorial, to keep it hands-on and motivate the reader.
  • Outline how to program for an event loop and write programs that don't block.

  • Needs to teach good taste. Example: Event handlers that are a tangle of special cases should be refactored into state machines. FedericoMenaQuintero should elaborate on this.

  • Examples in something other than C, to show that people should really use something more high-level to write GUI programs. Python is a possibility - it has good bindings, is well known and well liked by the community. Can we have a community of translators who would translate all the examples into all the common language bindings?

  • BjornLindqvist - There should be LOTS and LOTS and *LOTS* of images! For every class/struct/entity there should be atleast one screenshot showing it in action. For every code example one image of how it looks. There of course need to be LOTS of UML diagrams, interaction diagrams etc, too. Then maybe some photos that capture the essence, like photos that seem purely decorative. I mean, I don't think it would be possible to have enough images ever. There should also be truckloads of code examples too.

  • BrianCameron - It would be useful if developer documentation gave some indication about interface stability. Developer information should highlight which interfaces are stable, which interfaces are expected to change, and which interfaces should be avoided. This sort of information is dynamic (it can change as the code changes from release-to-release), so it would be best to document this in some form where it can easily be updated and maintained (docbook, for example, might not be the best format).

  • DuncanCoutts - It would be great to make it easier to generate documentation for language bindings from the same sources as the C docs. This would allow the language bindings to share most of the work that goes into the centeral C docs. It should be possible to automatically convert the C docs into the language bindings docs, probabbly with extra language specific bits. But it should be possible for the centeral documentation to be mostly language nutral - or contains sufficient markup to automatically translate for another language binding. Gtk2Hs (the Haskell bindings) already does semi-automatic translation from the C gtk-doc/docbook docs but it could be made much easier. For example having an annotation to indicate that a sentance/paragraph applies only to C (since it refers to C-isms like memory management issues) would make the docs easier to translate for other languages. Extending gtk-doc to produce simpler formats than docbook would also make translating to other formats much easier (such as language specific documentation markup formats, eg Javadoc, Haddock etc).

  • PatanjaliSomayaji: The documentation needs to be linked to a specific version of GTK+/GNOME. Currently its not always clear what version of a library/API is being referred to by a document, even at the level of whether 1.x or 2.x is being targeted.

Working with existing documentation

OwenTaylor: While we don't have perfect documentation, we have a lot of documentation already. A succesful effort here will integrate into that framework: standalone documents tend to be unmaintained, documents maintained with sourcecode have natural maintainers. For example, many of the topics listed below naturally are parts of the GTK+ documentation ("Implement drag and drop")... where this should go is as part of the current GTK+ documentation book. (The current "reference manual" can be extended to include chapters that are less referency very easily.)

We may need some new GNOME-platform-wide documents, but we shouldn't be creating confusion: documentation of libraries belongs with those libraries.

MurrayCumming: I assume that we want to create a single high-level document. The alternative would need some plan for gathering the various sources together, but even then we would have less coherent documentation. We must therefore live with some duplication and the resultant maintenance problems. But we can lessen this by

  • Avoiding fine details and referring people to the more exact documentation.
  • Describing APIs in terms of an example that we refer to for other parts of the API too.
  • Building examples as part of the documentation build system, with the deprecation defines, so they are always up-to-date.

Unrealistic Goals

  • In the Gnome API Documentation include a link to a single source file.c of a working gtk app, with every function description. The source file should showcase the most basic use of that function. Reason: for most beginning users, code snippets are not enough, it is really nice to have a working example instantly available. This would greatly increase the ability to learn the GTK api.

    • Also a link to (or inline) screenshot showing the results of would make it easier to recognize which options one would want to use. For example Details of Boxes from GtkTutorial should be in the GtkBox documentation.

    • MurrayCumming: An example and screenshot for every single function is just not going to happen. An example and screenshot for every widget is, however, possible - gtkmm mostly does this, though in the book instead of the reference.

Rejected

  • Pick a coding style and stick to it in file naming, classes, functions, variables, etc. ("GNOME certified" could be suggested)

    • MurrayCumming: Yes, it's sensible to have consistent examples, but it's madness to tell someone they aren't GNOME if they use different whitespace.

      • TommiKomulainen: What I meant was that using (any) consistent coding style would be beneficial but in no way basis for exclusion. At least for open source projects being consistent would lower the barrier for others to get familiar with the project. Not an entry criteria or anything, but something to recommend.

      • ShaunMcCance: I don't think the book needs to discuss or recommend a particular coding style. However, a consistent coding style should be used throughout the book. This will make the book feel more coherant, and will actually go a long way towards encouraging people to use that coding style.

  • Overview of nearest and long-standing Gnome goals - the most important places where help is needed. For example, main tasks for current release cycle and general plan of Gnome development.

CategoryDocumentationProject

DocumentationProject/IdealDeveloperDocumentation (last edited 2023-07-27 08:46:05 by AndreKlapper)