MDN/Archives/Documentation automation tool

Let's design a tool for editing and automatically generating patches for documentation to be included in IDL and header files.

Initial notes

• At the MoCo all-hands, we discussed ways to improve our reference documentation process, and the idea was proposed that we develop a tool that would pull an IDL or header file, let you edit it, test the JavaDoc HTML output, then let you submit a patch with a diff of the comments once you were finished in order to get edited comments into the tree. This would let writers work more or less directly in the headers and IDL files with a minimum of effort, and we could then switch to automatically generated reference documentation.
  • See PyDocWeb as a possible inspiration.
  • Can we do something where you edit WYSIWYG then get the comments regenerated?

Patch generation and submission

Once editing is finished, a single button (with a Bugzilla login) should let you generate and submit a patch. This should include a human-written summary of the patch, with the patch itself and a link to preview what the docs will look like on MDN.

Questions

• How will translations fit into this tool?
• How to keep the process simple, make it easy for people to contribute?
• Do we continue to document removed methods etc as we currently do?
  • If so how will the tool manage this?
  • It would probably be easiest to just generate documentation for each Gecko version individually and the site would allow selecting the Gecko version to view, and possibly a diff between versions.