A major part of contributing to MDN documentation on any significant scale is knowing how to work as part of our community. This article offers tips to help you make the most of your interactions with both other writers and with the development team.
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.
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.
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.
When writing documentation to cover changes implemented as a result of a bug in Bugzilla, you'll often interact with people 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.
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 #devmo 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 dev-mdc mailing list. In general, IRC tends to be used for quick, more in-person-like discussions, while the mailing list is typically used for longer-duration conversation.
By keeping in mind the General etiquette guidelines, you'll find that usually things go very smoothly.