DXR | Doccelerator / Bespin / source doc editing
jen at mozillamessaging.com
Fri Jul 16 01:03:23 UTC 2010
Hi. At the Summit, I talked to a few people about making the source
documentation (embedded in the source files) more accessible and easier
== 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
- 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.
== Proposal ==
- Integrate Bespin into DXR or Doccelerator (not sure which platform is
more appropriate for this).
- Limit the Bespin integration so that *only* documentation portions of
the source code can be edited.
- Expand Bespin 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.
== Other Notes ==
- Serendipitously, David Humphrey is "Restarting DXR Development"
- Currently, Sheppy manually copies and pastes docs from the source to
MDC, and then annotates. This innovation would probably be useful for
the Firefox team as well.
Please comment. I'll write a more formal plan on the wiki that includes
the results of the discussion.
More information about the tb-planning