One thing that we've learned at MDN is that when the development team and the documentation team for a given project, API, or technology work closely—and well—together, the documentation quality is incredible. This guide offers some suggested tactics for how the developers and writers can work hand-in-hand.
This article is a work-in-progress, living document. If your dev/doc collaboration discovers more ways to work well together, please feel free to add those ideas!
Linking up
Ideally, when a new technology or project begins development, the dev team will let the writing team know that there's something coming that will need documentation. Sometimes that doesn't happen, and the MDN team does monitor Bugzilla watching for work that will need documentation, but in a perfect world, we'll get advance notice in a direct way.
The best way to notify the MDN team of a new project that we need to be aware of is to file a documentation request bug. Providing a list of who to contact with questions is a great way to help! Including a link (or links) to the bugs related to the project is also a big help.
Sharing information
There are several useful ways to share information. Here are some suggestions.
Bugs
Simply ensuring that the documentation team is flagged on bugs that affect the documentation is a huge help. Proper use of the dev-doc-needed keyword and of comment tags can go a long way. See Getting documentation updated for details.
Meetings
Dev teams usually have meetings. When possible and useful (and it's often quite useful), the MDN team tries to have someone attend these meetings. It's a good way to know what's going on, what schedules look like, and so forth.
In addition, the writers working on large documentation areas, such as the Web APIs documentation, often hold meetings just for the state of that documentation. The writers love having a representative from the development team attend these meetings; it's insanely helpful for everyone involved.
These are typically short check-in meetings with an agenda similar to this:
- Quick status updates from the contributing writers.
- Questions/updates from the development team for the writers: this may include questions about the state of specific documents, information about specific content that's urgently needed, notes about problems with the existing content, and so on.
- Questions/updates from the writing team for the developers: this is an opportunity for the writers to ask questions such as whether or not a specific bug is expected to land anytime soon, whether or not anyone might be able to review a particular document, whether there's a specific engineer that might be able to answer questions about a given API, and that sort of thing.
The Developer Content Coordination Meeting is held every Tuesday at 9 AM Pacific time in the "mdn" channel on our Vidyo videoconferencing system (also available by telephone). In this meeting, the MDN writing community, the developer relations team, the API development team, and others meet to exchange information about what we've been working on, what's coming up, and what the most important things are to share with developers. This allows us all to be on the same page about priorities for promoting and documenting topics, and lets us provide feedback to the developers that may help inform them in useful ways. Everyone gets a lot out of it, and it usually lasts about 30 minutes, sometimes less.
Work weeks
If your dev team has a work week or meetup, you should seriously consider inviting the writer(s) that are handling the relevant documentation. This has many benefits, including:
- Improved communication by having the writer there first-hand to learn what's going on.
- Improves relationship between the writers and developers by having them get to know each other better.
- Provides great access and convenience for the writers to find the right people to talk to.
- Offers a special opportunity for one-on-one conversations to answer ongoing questions or to resolve problems.
If you're having a work week and don't know if you have a writer assigned to your topic area, feel free to email the doc team lead, Jean-Yves Perrier, and he'll see if he can find someone to go. We will try to get someone there (or, better, to get a writer assigned to your project)! Keep in mind, though, that the writing team is small, so finding someone to attend a work week on short notice is tricky.
Doc status pages
Larger documentation projects on MDN now use doc status pages to keep track of what needs to be done, and what has already been done, to get the work done. These pages provide a list of tasks that need to be accomplished as well as the state of each of those tasks.