複数チームによる文書作成のための協力

私たちが MDN で学んだことのひとつは、開発チームと文書作成チームが共にあるプロジェクト、API、またはある技術について密接に協力して文書を作成した場合、その文書の品質が素晴らしいということです。このガイドは開発者と文書作成者が手と手を取って協力するための戦略を示唆するものです。

つながり始める

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.

情報を共有する

There are several useful ways to share information. Here are some suggestions.

バグ

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.

ミーティング

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:

1. Quick status updates from the contributing writers.
2. 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.
3. 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 Web API documentation meetings have been being held for many months in Vidyo with great success. Each week, the Web API dev team has sent at least one (and often two) members to the meeting, and we've been incredibly productive, while typically holding the meetings to 15 minutes or less.

集中作業週間

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, Eric Shepherd, 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.

文書化の状態を表示するページ

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.