Wishlist for Developer Docs

In Bug 1513652 on Bugzilla, Ben laid out what he would like to see documented in the docs. Below is what he said.

Also, I've been compiling a sort of wishlist for what I'd ultimately like to see in a TB development guide.

Most of the bullet points are a little arbitrary and incomplete, but hopefully it gives a flavour.
I've split up into 3 main sections: "Getting Started", "Reference" and "Architecture".

Again, a lot of these things could be annotated links to existing docs, at least to begin with.

---

Getting Started

• Updated Start_Hacking guide
• Assorted "How To" guides
  • how to add a unit test
  • debugging tips
  • TB-centric Bugzilla guide
• Where to ask for help
• Relationship between M-C and C-C
• High-level architectural view

Reference

XPCOM reference

• Overview - goals, issues, common pitfalls
• Best practices/patterns/idioms
• API reference
  • Index of core platform APIs - strings, XPCOM, file access etc
  • Index of firefox APIs
  • Index of TB APIs
  • Note clearly which ones are being phased out, and their replacements
  • Docs autogenerated from code where possible, but make sure not to overwhelm with detail.
  • Curated index of important APIs
  • Ongoing effort to improve/clarify docs.
    If you can't easily document an API, then it's probably too complicated :-)

C++ environment

• C++-specific APIs
• Coding style
• Thread safety rules
• Linting/static analysis tools

JS environment

• JS-specific API reference (eg OS.File et al)
• preferred idioms
  • async/await vs promises vs generators
  • modules (do we have our own module system or are we moving toward some existing standard?)
• coding style
  • to run linter to check
• GUI (eg are we shifting from XUL to more HTML-based?)

Testing

• unit tests
• mozmill/mochi/whatever
• how to run/write/debug tests

Tools

• mach
• linting
• testing

Source layout

Index of stuff which is deprecated/on the way out and what replaces it.
(eg using OS.File over nsIFile),

Curated index of interesting/useful blog posts/articles about TB development,
with some indication of relevance/staleness.

Architecture

Concepts, intentions, aspirations.
JS/C++ split - where the boundaries should be.
Threading model
Plugin/extension model

Start with the linked Bugzilla proposal and review the requested Getting Started, Reference, and Architecture sections. Break the wishlist into independently actionable documentation tasks, identifying existing material to link where possible. Done means the broad wishlist has become a scoped, maintainable developer-guide plan.