How to Document Mozilla

by Alec Flett

This document will attempt to explain the process by which you should document pieces of mozilla. 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 obtaining access to edit documents on mozilla.org, please see the contribution page.

This document does not cover formatting of your document, styles to use, HTML coding conventions, etc. (That is 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
Gathering Information
Writing the 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 plugin 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 indended 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 signifigant 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 codebase. 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 codebase. 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 of other products who want to embed mozilla:: 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.
End users: Most end user documentation is found within the Mozilla product, but extra end user documentation on mozilla.org should not expect a lot of technical expertise from the reader.
Others: There are many permutations of prospective readers, and it is important that your target audience be defined, if only for yourself.

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:

HowTo: A HowTo is usually process oriented, and walks 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 plugin, how to add an item to a menu, or how to add a new CSS property. HowTos 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 seperate section for each method.
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 soley 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.
Technote:: Sometimes a simple one or two page document sufficies to describe a very specific problem and solution. A technote is often much like a HowTo, 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 prexisting knowledge. Sometimes technotes can evolve into full-fledged HowTo's.
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: creativly 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 you examples are too complex, or you include too much detail, users don't know which aspect of you 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 anamolies 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 seperate 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 seperate 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. The above are only a small samples of possible scopes.

The important thing to remember is to keep your scope consistent throughout your document. The easist 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 research. 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 you document is complete.

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

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

Questions to ask

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 critiques.
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 CVS blame 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 with them trying to 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.

everything below is under construction

Tools that will help

LXR: browse source code with cross references and search tools
CVS Blame: look at who is working on which parts of the code, see what areas of code are often revised
Bonsai: look at checkin comments, see who's working on what, and what changes are going in
tinderbox: look at who is most active both outside and within the scope of your document

Mozilla