How to document Mozilla projects

This document attempts to explain the process by which you should document Mozilla related subjects. In some sense, this document is just a "how to be a tech writer" with lots of Mozilla-specific information thrown in.

For details on how to use the wiki, see the Getting started guide.

This document does not cover formatting of your document, styles to use, HTML coding conventions, etc; those are covered in the Style guide. It does include guidelines for document structure but many factors may determine the structure or approach for your document.

About your document

Before writing a document you need to determine exactly what you are trying to write. Is it an overview of a module? A guide for end-users? A FAQ for plug-in authors? Once you have established the goal of the document, you will be able to rely on that goal when deciding what to include and what to ignore.

Below you will find a few important questions that you should know the answer to before you even begin.

Who is your audience?

Mozilla has many clients, and it is important to try to imagine yourself as one of these clients when reading your document. Not every client wants to read every document, so some amount of duplication among various documentation is fine. The key is to make sure your intended audience maintains interest and understanding of your subject matter. Think about how much you expect the reader to know. Constantly ask yourself if the material you are presenting is relevant and appropriate for your readers.

A few of the more significant groups include:

Developers working on Mozilla itself: These developers often need very precise descriptions of subsystems, lots of sample code, and so forth. Developers are often somewhat familiar with Mozilla already, and do not necessary need verbose descriptions of every little thing, but may need to know of obvious pitfalls and mistakes in the existing code base. The history of a module or subsystem may be important to explain the design of existing code, in the case where legacy code does not necessarily reflect new directions that may be expressed in your document.
Developers working on Mozilla extensions: These developers interact with only a few specific modules, and may be less familiar with the code base. Code or API history is not often relevant as they are developing for the current and future versions of the product and may not be exposed to legacy code. Public (frozen) APIs and private APIs may need distinction. Suggestions for the proper API to use for specific cases can be very helpful.
Developers that want to embed Mozilla in other products: These developers often do not care about the nitty-gritty details of how a particular API works or where it is going. They often want a very process-oriented approach to plugging their own application into Mozilla or vice-versa. Often they care only about binary compatibility with future version of Mozilla and thus should be steered towards frozen interfaces.
Web developers: Developers creating web applications or designing web sites also come to the Mozilla Developer Center for documentation.

If you write a document, Extending menus with overlays, you might ask yourself if the user knows what an overlay even is. If they don't know what one is you might decide instead to write Extending menus in Mozilla and include a brief overview of how overlays allow extension of the UI. Or perhaps they know what an overlay is and have used them before to add icons and UI, but don't know anything about menus in particular. Your document might become a description of the positioning features of overlays, to make sure menu items appear in the right place.

What kind of document will this be?

It is important to determine the type of document you are writing so that you can determine its structure. Otherwise you will just end up with a mishmash of tips and tricks without any obvious path to enlightenment in the area you are covering. Try to choose one document format, and stick with it.

While you should feel freedom to structure your document in your own unique way, most readers are familiar with a few common document types. If you choose one of these document types, your users will be able to navigate your document easily. Here are a few suggestions:

How-to: A how-to is usually process oriented, walking the user through a fairly real scenario. Tips and tricks are offered along the way, as well as possible pitfalls. Typical documents like this might include how to create a plug-in, how to add an item to a menu, or how to add a new CSS property. how-tos often include a few large examples that the user learns over the course of the document.
Reference: API references are usually documents whose structures closely match those of a particular API. There might be a chapter for each class and a separate section for each method. We have templates and examples of various types of API documentation.
Module architecture guide: This kind of document describes the inner workings of a particular module. It is often intended to flush out architecture problems and describe future direction of the module itself. Code history can explain existing architecture. Often these guides are intended solely for the current and future developers of the module. They may also include descriptions of how to extend the existing design.
Module consumer guide: This kind of document describes the external APIs for a module. Usually this document is intended for people who might use this module but do not necessarily care about how the module works or what future directions it may be taking internally. More elaborate than a simple Reference, the guide should show examples describing recommended practices and common patterns.
FAQ (Frequently Asked Questions): Usually this is just a list of topics that a reader should understand. Answers to the questions are often brief, giving an answer without justification and/or history, but reference other documents which describe the answer in much more detail.
Technical note: Sometimes a simple one or two page document suffices to describe a very specific problem and solution. A technical note is often much like a how-to, but its scope is very limited and intends to document something very specific. No background is given and many assumptions are made about a user's preexisting knowledge. Sometimes technical notes can evolve into full-fledged how-tos.
Other: There are many other document types out there, and often the content or target of your document may determine your document type automatically. The key is to be flexible: creatively structure your document to engage and educate the reader, but present it in a familiar enough format that you do not scare someone away from finishing your document.

Determine your scope

Scope is a particularly difficult problem. You need to decide if you are going to document an entire module, a simple process, an elaborate architecture, or something else. More often than not, documents try to cover too much, in too much detail. When in doubt, cover less rather than more. If your document is only an architectural overview, don't go into detail on the use of strings in the module. If your document is about something as specific as character set conversion, don't discuss localization or how to avoid excess string copying.

One of the difficulties in determining the proper scope of your document is that readers themselves often can't determine what is useful information and what is not. If your examples are too complex, or you include too much detail, users don't know which aspect of your document is important, and which details are inconsequential.

The biggest benefit from determining your scope is to limit how much you write. Here are a few examples, though the concept of scope is much less granular than some of the other questions above:

Module overview: A description of the structure of a module, including descriptions of the way subsystems interact within the module. Minor edge cases or anomalies in the design should be ignored or played down. Pictures and process flow will guide the user to understanding of the overall concepts, and leave it to the user to find specifics in other documents. An example might be a general overview of XPCOM which describes the concept of the component manager, factories, creating objects, and so forth. Further detail such as the details of creating a DLL might be better left to a separate document which specifically describes the creation of a XPCOM DLL.
Subsystem guide: A detailed guide describing a particular subsystem in great detail. An example of this might be a guide to array classes, which gives specific examples in C++ and JavaScript about accessing array members, manipulating arrays, and so forth.
Tutorial: When covering a specific topic in a tutorial fashion, it helps to make assumptions about what the user knows, and direct them to other more documents before straying off the course of the tutorial. When a writer feels the need to describe something like this more completely, a separate document can be written describe this alternate topic. For example, in a tutorial about adding items to a menu using overlays, it is probably not useful to include a sample JavaScript component, let alone describe what the sample does.
Others: There is a tremendous range of possible scopes in documents. These are just a few examples of possible scopes.

The important thing to remember is to keep your scope consistent throughout your document. The easiest way to do this is to decide on your scope early in the writing process, and stick to it. If your document evolves to cover a greater (or lesser) scope, make sure to thoroughly check the entire document to ensure the level of detail and abstraction is consistent.

Gathering information

Once you have planned out the overall direction of the document, you can begin your research about its content. If you are an expert in the area you intend to cover, then much of your research may simply be gathering minor details to ensure your document is complete.

Find existing information

There's a lot of information out there, and it can be tricky to hunt down the exact help you need. Here are some tips to get you started.

Existing documentation: It is important to be aware of existing documentation on the subject you are covering. As mentioned above, duplication of topics in documentation is fine, as long as another aspect of the document is different. For instance you might find a reference for XPCOM, but you might notice that there is no tutorial. Use the details of the reference to develop your tutorial.
Module owner lists: Mozilla projects work on a "module owner" basis; each major component has an owner or owners who are responsible for what goes on there. These owners are often your best source of information — or at least a great way to find the right person to talk to.
Mozilla source cross-reference: MXR, the Mozilla cross-reference, lets you access all the source code for the Mozilla project (with the exception of some things, like much of Firefox OS, which is located on GitHub). The code and its comments are often a great resource for information.
Mozilla wiki: The Mozilla wiki — often referred to as "wikimo" — is a repository of process and design notes, drafts, plans, and preliminary specifications. Despite being often a cluttered mess, it's a treasure trove of invaluable information.

Read the code

As is often the case with open source projects, the code is the documentation for many modules. Developers are used to reading the source code of a module, as well as looking at other consumers, in order to learn how to use it.

How to deal with developers

Before talking with developers, try to become as familiar with a module as possible before asking people about it. Most importantly, be ready with specific questions. Here are a few other tips and tricks for dealing with developers.

Explain that you're writing documentation. If developers have a sense of why you're asking so many questions, they might be able to better direct you to places where you can learn more. They might also be willing to explain larger concepts if they realize that you're documenting, and not just hacking something together.
Be sensitive to people's jobs. Like many folks working on Mozilla, developers are usually overburdened and don't have time to hold your hand as you learn a new module. If a developer tells you to go learn something before asking any more questions, do it. Go back to the source and learn some more.
Request examples in the source code. Often a developer is going to be adept at using tools to point you at good examples.
Don't ask anyone to write code. Unless it is offered to you, don't expect anyone to write new examples for you. One option is to write your own example and ask a developer for an opinion on it.
If a developer isn't receptive, try someone else. Don't keep asking the same person the same thing over and over. If a developer blows you off, use Mercurial's blame feature to find other experts, or ask him/her who else knows the module well.
Demonstrate your current knowledge. Don't waste a developer's time by making them figure out what you do and do not know. Explain your current understanding, even if you think it might be wrong. A developer can often steer you the right way without having to go into lengthy explanations.

Helpful tools

There are a number of helpful tools and resources you will find invaluable as you work on documentation for Mozilla:

MXR: The Mozilla Cross-Reference is a tool that lets you easily search and browse the source code in your browser.
Blame: Mercurial (the version control system we use on Mozilla) offers a blame feature, which lets you see who has been working on which parts of the code. You can also see what parts of the code are most frequently revised.
Tinderbox: Tinderbox lets you look at the status of the tree (whether the code is currently building correctly or not), who is most active on the code, and other helpful information.

Original Document Information

Author: Alec Flett