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?
  • Do we forgo translations of references and rely on translated how-to guides instead?
  • Or do we allow translations but have them continue to be a manual process based off automatically-generated English references?
• 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.
• Should examples and other information that is not included in source files be included on the page, or as a separate page?
• How will bug spaming be prevented?
  • Each page could have a bug number associated with it, so that a new bug is not generated each edit.
  • Should patches be 'batched', that is:
    • A patch is generated once per day;
    • X hours after last edit;
    • After editorial review
    • How about separate "save draft" and "submit patch" buttons?