DXR | Doccelerator / Bespin / source doc editing

Jennifer Zickerman 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 
to maintain.

== 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.


== 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" 
(http://vocamus.net/dave/?p=1128)

- 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.


jen.



More information about the tb-planning mailing list