Thunderbird/Docs/Source editing

DRAFT: This is a work-in-progress. It will be announced and comments solicited soon.

This page describes a proposal to augment one of the web-based code mapping and cross-referencing tools (DXR or Doccelerator) to enable source code comment editing and patch generation.

Background

Much of the Thunderbird documentation that is relevant to developers (especially extension developers) is stored in the Thunderbird source files. In the Thunderbird world, we use the Mozilla Developer Center for explanatory documentation (such as examples and code samples) and, as needed, link to the documentation in the source files (generally via the MXR interface). The MoCo (Firefox / Gecko / etc) folks, on the other hand, manually copy documentation from the source files to MDC, and then format, annotate and add explanatory text.

Problems / Opportunities

There are several problems with the current model:

• There

• Developers will write more documentation if they are happy with their documentation tools and if the documentation that they write is easier to find. The MDC platform is difficult to work on and it will be many months before this situation might improve.

• It is impractical for non-developers to help with the
• For Thunderbird

Proposal

• Integrate Skywriter into DXR or Doccelerator (not sure which platform is more appropriate for this).

• Limit the Skywriter integration so that only documentation portions of the source code can be edited.

- Expand Skywriter so that it can generate a patch (which subsequently gets attached to a bug). Maintainers could integrate these patches without worrying because they only impact documentation.

Reasons

- It's more efficient to single-source documentation, rather than have some documentation in the source code and some in whatever publication platform we are using (such as MDC).

- We could (some day) enable automated export / update mechanisms (where, for example, we could dump (or dynamically look up) documentation from the source repository and make it accessible on the publication platform).

- It would be easier for programmers to contribute and review doc changes by making this part of the patch integration cycle.

- It would make it easier for non-programmers to help with the docs.

== Problems ==

- It's hard to integrate documentation into the development / release cycle. We need to be able to modify the documentation without impacting development processes (by working independently of the release cycle).

- We need light-weight editing tools. While a developer downloads the source tree and uses an IDE, this is pretty heavy for others who, for example, are just doing some simple edits. Instead, it would be really handy to use cool tools like DXR | Doccelerator and Bespin.