A major part of contributing to MDN documentation on any significant scale is knowing how to work as part of the MDN community. This article offers tips to help you make the most of your interactions with both other writers and with development teams.
General etiquette guidelines
Here are some general guidelines for conduct when working in the Mozilla community.
- Be polite! Even in disagreement, we all have the same mission: the betterment of the Web.
- Ask, don't demand. People are far more likely to be helpful and responsive when you politely request help rather than demand it. While the documentation work is important, and our development community knows it, human instinct tends to cause people to be abrasive and difficult if you don't treat them with due respect.
- Balance your need for information with the urgency of the documentation and the time the others in your discussion have to devote to helping you. Don't keep pushing for more and more details if it's not absolutely necessary right away, to the point of driving the others involved in the conversation crazy.
- Keep in mind that your request takes valuable time from the people you're contacting, so be sure to use their time well.
- Be considerate of cultural differences. Mozilla is a multinational and multicultural team, so when talking to someone whose culture is, or may be, different from your own, be sure to keep that in mind while communicating.
- Start a new conversation instead of highjacking an existing conversation. Don't inject your questions into an unrelated conversation just because the people you need to talk to are paying attention to it. While convenient for you, this can irritate the people you're trying to talk to, and result in a less than ideal outcome.
- Avoid bikeshedding. Don't let your enthusiasm become annoying pedantry. It makes conversations cumbersome and unfocused.
Be tactful
Always be tactful and respectful when communicating with others.
Politely pointing out mistakes
If your purpose in contacting someone is to ask them to do something differently, or to point out a mistake they've been making (especially if they repeatedly do it), start your message with a positive comment. This softens the blow, so to speak, and it demonstrates that you're trying to be helpful, rather than setting you up as the bad guy.
For example, if a new contributor has been creating lots of pages without tags, and you'd like to point out this problem, your message to them might look like this (the stuff you'd need to change for each case us underlined):
Hi, MrBigglesworth, I've been noticing your contributions to the Wormhole API documentation, and it's fantastic to have your help! I particularly like the way you balanced your level of detail with readability. That said, though, you could make these articles even better and more helpful if you added the correct tags to the pages as you go.
See the MDN tagging guide (https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Tag) for details.
Thanks again, and I look forward to your future contributions!
Sharing knowledge
As you participate in the MDN project, it's useful to know what's going on, and to interact with other members of our community. By talking with others in our community, you can get—and share—ideas, status updates, and more. We also have tools and informational resources that can help you know what's being done, by whom.
Communication channels
There are several ways you can engage with community members (either developers or writers), each of which has some of its own particular rules of etiquette.
IRC
This is often the quickest and most direct way to approach someone: just ping them in IRC. Find the channel corresponding to the topic area you're writing about and just talk to them. For IRC-specific etiquette tips, see the Mozilla Support article "Getting Started with IRC." For discussions about developer documentation, use the #mdn channel.
Bugzilla
When writing documentation to cover changes implemented as a result of a bug in Bugzilla, you'll often interact with people involved in those bugs. Be sure to keep the Bugzilla Etiquette guide in mind at all times!
Sometimes, a private email exchange between you and one or more other people is the way to go, if you have their email address.
Note: As a general rule, if someone has posted their email address on documents about the technology you're documenting, has given you their email address personally, or generally has a well-known email address, email is an acceptable "first contact" approach. If you have to dig for it, you probably should try to get permission in IRC or a mailing list first, unless you've exhausted all other attempts at getting in touch.
Content status tools
We have several useful tools that provide information about the status of documentation content.
- Revision dashboard
- The revision dashboard provides a fantastic tool to review changes made to MDN content. You can see recent history, choose a range of time to view, and filter based on things like locale, contributor's name, and topic. Once you're looking at a set of revisions, you can view the changes made in each revision, quickly open the page, see a full history, or even revert the changes (if you have those privileges).
- Documentation status overview
- Our documentation status overview page provides a list of all the areas of MDN that have been configured for status tracking, with information about how many pages therein need different types of work done. Click through to a particular topic area to see detailed lists of content that needs work, such as pages that have no tags, or are tagged with indicators that certain types of work need to be done. You can even see lists of pages that haven't been updated in a long time and may be out of date, as well as a list of bugs that have been flagged as impacting the documentation in that area.
- Documentation project plans
- We have a number of writing projects that are in the planning stages, or are large and ongoing, for which we have written planning documents to help us keep track of what we need to get done.
- MDN Taiga
- The MDN staff writers use a tool called Taiga to manage current and future documentation projects. You can take a look to see what we're doing and how it's going, and you can see what projects we'd like to see happen soon. Some of those will be taken on by staff writers, but you should feel free to take one over if you like! For more information about the agile processes followed by the MDN team, see our Process page on the Mozilla wiki.
The development community
Possibly the most important relationships to develop and maintain, as a member of the MDN writing community, are those you develop and sustain with the developers. They create the software we're developing, but they're also the most useful source of information we have. It's crucial that we maintain good relations with developers—the more they like you, the more likely they are to answer your questions quickly, accurately, and thoroughly!
In addition, you represent the MDN writing community. Please help ensure we keep our excellent working relationship with the dev team by making every interaction they have with the writing team be a good one.
On a related note, a great way to find the right person to talk to is to look at the module owners lists.
The writing community
The writing community is a large one. While the number of extremely frequent, or large-scale contributors is relatively small, there are many dozens or hundreds of people who contribute at least now and then. Fortunately, these are by and large awesome people with a genuine love of the Web, Mozilla, and/or documentation, and interacting with them is almost always pretty easy.
See the article Join the community for more information about the MDN community.
The most frequent place you'll directly interact with other writers is in the #mdn channel on IRC. This channel is specifically reserved for discussing documentation. For IRC-specific etiquette tips, see the Mozilla Support article "Getting Started with IRC." You'll also have discussions with us on the MDN discussion forum. In general, IRC tends to be used for quick, more in-person-like discussions, while the discussion forum is typically used for longer-duration conversation.
By keeping in mind the General etiquette guidelines, you'll find that usually things go very smoothly.