Documentation Team » Planning »

Developer Documentation Plan

This page details plans to overhaul the developer documentation in Gnome. This plan was developed by ShaunMcCance, the DocumentationProject leader and lead Yelp developer.

Background

Good developer documentation is vital to the success of a developer platform. It attracts new developers and helps create seasoned experts. It is one of the first impressions developers get, and a key factor in the decisions of commercial developers. Documentation can literally make or break a project.

The Gnome platform has a reputation for being under-documented. Gnome developers are sometimes defensive, because they feel the API references are complete. Indeed, API documentation is a requirement for API additions in modules in the platform release. This is a great start, but it's not enough. The existing documentation serves some people very well, but it does not serve everybody it needs to.

Gnome does have some non-reference documentation, and much of it has been collected into gnome-devel-docs in the last few years. With library.gnome.org, Gnome is able to present all of its documentation on the Internet. Along with tools like gtk-doc, these are central to the existing documentation system, and will provide the foundation for this plan.

Goals

1. The documentation should be accessible to new developers. New developers should feel empowered within their first day of working with the Gnome platform.
2. The documentation should support exploratory learning after the initial introduction. After the introductory tutorials, we should avoid a steep jump in the learning curve.
3. The plan should be feasible within the Gnome community. Volunteer community members are unlikely to commit to writing large books.
4. The documentation should be maintainable. We need good developer documentation now and five years from now. We should ensure that the systems we develop will be actively maintained and built upon over the years.

Outline

This proposal deals with the following types of documentation:

• The Platform Overview provides a brief topic-oriented overview of the technologies Gnome wants to promote.
• Introductions are short tutorials that assume as little as possible about the reader. These are geared towards new developers.
• Howtos are possibly longer tutorials that assume the reader understands the basics and walk the reader through something.
• Guides are longer documents that present information that doesn't fit into references.
• References provide details for API.

This proposal intentionally does not deal with manuals or other book-length instructional documents. While these are a wonderful addition, they are extremely difficult to develop and even harder to maintain. Focusing on manuals first is likely to block the entire plan.

Introductions

Introductions are quick tutorials on a given topic. There should be at least one primary introduction for every library in the platform, and that introduction should walk the reader through creating a basic application using that library. For many libraries, there should be additional introductions for particular functionality.

Introductions should assume as little as possible about the reader. For an introduction using C, the reader is expected to know how to program in C, but is not expected to know autotools/make, pkg-config, or the particular compiler invocations that are necessary. Whenever possible, introductions shoudl avoid assuming the reader knows any other library in the stack. Sometimes, this is unavoidable. For example, an introduction to WebKitGtk needs to assume familiarity with GTK+. When this is the case, the introduction should clearly state the required skills.

An introduction should take no longer than half an hour for a typical target reader to work through. Note that "work through" is not the same thing as "read".

Each introduction should be mirrored in different programming languages to reduce the barrier to entry.

Howtos

Like introductions, howtos are standalone tutorials. Unlike introductions, however, they may assume the reader has a basic familiarity with the Gnome platform. Howtos present more complicated tasks than introductions. This is an opportunity for seasoned hackers to write about things that excite them.

Howtos do not need to be mirrored in different programming languages. This would be infeasible with a large number of howtos. Programmers with enough experience should be able to pick up concepts from howtos written in any sane language.

Guides

Guides are larger books or topic-oriented documents that present information that doesn't fit into API references. Guides will often be the primary source of certain information. The following guides should be addressed initially:

• Internationalization Guide
• Build Tools Guide
• Accessibility Developer's Guide
• Optimization Guide
• Desktop Integration Guide
• Documentation Guide
• Human Interface Guidelines
• Document Style Guidelines

Note that many of these currently exist in some form. Each of these guides requires its own planning session.

References

Gnome uses a number of automated tools to extract API references from source code. The primary tool for C libraries is gtk-doc. Some of the language bindings may use the API documentation tools that are common to their language. This is a good process, and should be kept. But we should build transformations to present all of these on library.gnome.org with a consistent style and with a consistent information chunking granularity.

All of the API references need an audit to ensure quality. API documentation tools usually allow you to measure completeness, but completeness is not the same thing as quality. Only an experienced human being can determine quality. Guidelines for auditing API references should be developed.

API reference pages need to be chunked into smaller units of information. Currently, gtk-doc documents have a single page for every header file, which generally corresponds to a single class or interface. This single page contains the full descriptions for all structs, enums, functions, properties, style properties, and signals defined in that file. Furthermore, deprecated functions are mixed in with non-deprecated material, making the entire page difficult to scan for relevant information.

For object-oriented references, the following strategy is recommended:

• A single page will introduce a class. It will have a brief description, the object heirarchy, and the implemented interfaces. It will then have separate synopses for constructors, structs and enums, properties, style properties, signals, and functions. Following that will be any additional information, in sections.
• Properties, signals, structs, enums, and functions will have their complete documentation on separate pages. It may make sense to group multiple things together on a single page for some APIs. Whenever possible, these pages should contain examples.
• Constructors are listed separately from other functions.
• Functions that are getters or setters for properties are not included in the functions synopsis. They will be accessible through the property documentation.
• Deprecated functions will be listed on a separate page.

Continuity

All of the material discussed here should be available on library.gnome.org. Furthermore, it needs to be presented as a coherent body of documentation. Gnome's current developer documentation is disjointed. Readers should be presented with links to related information, even (and especially) when that information is in another document. A system needs to be developed to specify these inter-document links and to inject them into the built documents.

To help readers find the type of information they need quickly, related links should be grouped as follows:

• All introductions are in one group.
• All howtos are in one group.
• Each guide is its own group.
• All reference pages are in one group.

Details

The Platform Overview needs to be heavily revised. This depends in large part on the Gnome community deciding on which technologies it wants to promote. As more components are developed in places like freedesktop.org and added to the external dependencies, Gnome is pushing more technologies that are not part of its official release sets. The community needs to decide, independently of the release sets, which technologies should be promoted. This decision will affect not only the Overview, but also what other content is provided.

The Platform Overview will be rewritten as a topic-oriented document in Mallard. The introductions and howtos will be pages within a Mallard document. This makes it easier to add and modify individual topics, reducing the long-term maintenance burden.

Each guide will be written in either DocBook or Mallard, depending on what works best for each guide. A content plan should be developed for each guide as part of this effort, even for those that already exist.

References will continue to be written using the API documentation tools they currently use. Tools will be needed to create the output specified in this plan. Most API documentation tools can output to DocBook, so that can be used as a source for conversions to the specified page style.

Library Reference Mockup

Below is a rough mockup for the GtkLabel class reference page. Note the following:

• The Related Resources box on the right should appear on all pages, and links between documents. Links are organized by document type.
• The link trail above the title appears on all pages. It helps keep readers from getting lost in the document.
• The amount of information on a single page has been reduced. References for functions, properties, and signals live on separate pages.
• Functions that are just convenience accessors for properties can be accessed with the read/write links next to the property, and do not appear in list of functions. The accessor functions may be defined on the property pages.
• Deprecated functions are not listed on this page. There is a link to a page which lists deprecated functions.