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

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

この記事は今も作成中の、生きた文書です。もしもあなたの関わる開発者/文書作成者の協力の過程で別の方法を見出したなら、是非ここにそのアイディアを追加してください!

つながり始める

理想的には、新しいテクノロジーやプロジェクトが開発され始める時に、開発チームはライターチームに対し文書化の必要のある何かが出てくると知らせるでしょう。ときどきそうはならず、MDNチームはBugzillaを監視して文書化が必要な成果がないのか見ています。しかし完全な世界では、直接的な方法で進歩していきます。

MDN チームに新プロジェクトを知らせるための最良な方法は文書化リクエストのバグを報告することです。 質問の問い合わせ先のリストがあると助かります! プロジェクトに関連するバグのリンクが入っていてもとても助かります。

情報を共有する

情報共有の便利な方法がいくつかあります。このようなものです。

バグ

単に文書化チームに文書化に影響するバグでフラグを立てることですごく助かります。dev-doc-needed キーワードとコメントタグを適切に使すうのは長くかかることもあります。詳細は文書を最新化するを見てください。

ミーティング

開発チームは通常ミーティングをします。それが可能で役立つときには (役立つ場面は多いです)、MDN チームはミーティングに誰かを出席させようとします。何が起きているか、スケジュールはどうか、などを知るのは良い方法です。

加えて、ライターは大きな文書化エリア(例えば Web API 文書)で作業し、その文書化の状況のためだけにミーティングすることもしばしばあります。ライターは開発チーム代表がこうしたミーティングに出るのを好感します; 関係する全員にとって極めて有益です。

典型的にこれは短いチェックインのミーティングで、次のようなアジェンダを伴います:

  1. 貢献するライターの短い状況更新。
  2. 開発チームからライターへの質問/更新: 特定文書の状況の質問や、特に急ぐ特定コンテンツの情報や、既存コンテンツの問題への注意などを含みます。
  3. ライターから開発チームへの質問/更新: 特定のバグがもうすぐ解決しそうか否かとか、特定の文書のレビューが可能になったりするかとか、ある API の質問に答えられるエンジニアがいるのかどうかとか、ライターがそんな種類の質問をできるチャンスです。

Developer Content Coordination Meeting は毎週火曜日の太平洋時間 9 AM に、Vidyo テレビ会議システムの "mdn" チャンネル (音声のみもあり)で開催されます。このミーティングでは、MDNライターコミュニティ、開発関係チーム、API ドキュメントチーム、その他が集まって作業がどこまで進んだかや、何が出てきたかや、開発者と共有すべき最重要事項は何かといった情報交換を行います。これにより、全員がプロモーションの優先度やトピックの文書化のための同じページに乗ることができて、開発者にとって役立つ方法で知らせることのできるフィートバックを返すことにもなります。全員がそこから多くを得て、通常は30分か、少ないかくらいの時間で終わります。

集中作業週間

開発チームに集中作業週間やミートアップがあれば、関連ドキュメントのライターの招待を真剣に考えるべきです。これは多くの利益があり、次のようなものです:

  • 起こっていることを初めて扱うライターを派遣することによって、コミュニケーションが向上する
  • ライターと開発者がお互いを良く知ることによって、関係が改善する
  • ライターが正しい話し相手を見つけるのに便利なアクセスが得られる
  • 質問や問題解決のための1対1の会話をする、時別な機会が得られる

集中作業週間があって、あなたのトピック領域の担当のライターがいるかどうかわからない場合、ドキュメントチームのリーダーにeメールしてください(Jean-Yves Perrier まで)、そして彼が誰か派遣できるか確認します。行ける人を探します (あるいは、もっと良い場合、あなたのプロジェクト担当のライターのことも)! ただ覚えてほしいのは、しかしライティングチームは小さく、集中作業週間に参加できる人がちょっとした注意で見つかることはトリッキーです。

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

MDN の大き目の文書化プロジェクトでは文書化ステータスページを使って、作業を完了させるのに何をしないといけないか、また何がすでに完了しているか、追跡しています。このページは達成する必要があるタスクと、各タスクのステータスとを一覧にしています。

ドキュメントのタグと貢献者

このページの貢献者: wbamberg, Uemmra3, hamasaki
最終更新者: wbamberg,