チームの技術およびオンボーディング用ドキュメントの作成方法

この記事について
Terrence Caldwel、2015 年 8 月 31 日

成功する開発チームは、コード品質を落とすことなく、素早く動ける必要があります。開発者のクローンを作成することは (まだ) できないため、チームのスピードを上げるにはどのようにしたらよいでしょうか?

次の 2 つの戦略をお試しください: まず、新しいチーム メンバーのオンボーディングにかかる時間を短縮します。次に、チームが技術的な問題の答えを探すために費やす時間を制限します。  

ドキュメントの作成よりも優れた製品の構築に時間をかけたいのは当然のことです。同時に、チームが素晴らしい成果物を構築するためには、優れたドキュメントも必要です。Confluence は、標準技術ドキュメントを簡単に作成および文書化できるようにすることで、この矛盾の解決をサポートします。これにより、だれでも標準技術ドキュメントにアクセスして更新に参加することができます。Confluence を活用して、短期間でドキュメントを効率的に作成できるようになります。

チームが Confluence 内で作成できる 3 種類の標準技術ドキュメントをご確認ください。

1. オンボーディングのドキュメント

新入社員に最新情報を提供することは、開発スピードやチームの将来の成功のために非常に重要です。 

新入社員チェックリスト

新入社員はまず、ガイド付きタスク リストを提供します。エディター ツールバーから任意の Confluence ページにタスクを追加できます。

新入社員用タスク リストまたは 90 日プランでは、指示や便利なリソースを提供します。基幹システムやアプリケーションへのログイン方法、会社ポリシーなどの社内リソースへのリンク、およびチームのメンバーとの面談タスクなどを含めます。

 

tip/resting Created with Sketch.

Pro tip

チーム スぺース内に、汎用的な新入社員タスク リストを 1 つ作成します。新入社員が加わったら、そのページをコピーして、彼らの個人用スペースへ移動させます。彼らはタスク リストを編集してタスクを追加したり、タスクを完了させる期日を割り当てることができます。

文書化する方法

タスク リストは、正しい方向を示すための優れたリソースです。しかし、彼らに何を示せばよいでしょうか。新入社員が問題を自身で解決できるよう、便利なハウツー文書が必要です。

ブループリントのハウツー記事で始める - 基本レイアウトを提供しているため、コンテンツの追加に集中することができます。

 

 

tip/resting Created with Sketch.

Pro tip

すべてのオンボーディング ドキュメントに同じラベル (「オンボーディング」など) を追加します。すべてのドキュメントにラベルが付いたら、ラベル別コンテンツ マクロを使用して中央リポジトリを作成できます。

画像、コード ブロック、関連 Web コンテンツへのリンクをページに追加するのを忘れないようにしましょう。

 


ページの編集が完了すると、一番下にラベル別コンテンツ マクロが表示されます。このマクロは、現在のスペース内にある同じラベルのすべてのページを自動的に取り込みます。


 

ページが保存されると、同じラベルを持つページの動的なリストが表示されます。

 

2. アプリケーションおよびネットワーク アーキテクチャに関するドキュメント

これらのドキュメントは、チーム全体が、いつでも利用できるようにする必要があります。Confluence では、次のようにしてアーキテクチャ ドキュメントをまとめることができます。

 

 

tip/resting Created with Sketch.

Pro tip

ダイアグラム ツールを使用してアーキテクチャ図を埋め込みます。Atlassian Marketplace には、Gliffy と Draw.io の 2 つの優れたアドオンがあります。これらのアドオンではいずれも、Confluence 内でダイアグラム エディターを使用できます。Atlassian では、画像として添付できるシンプルなリレーショナル図を作成するために、これらのアドオンや websequencediagrams.com を使用しています。

アーキテクチャ ドキュメントで最も重要なのは、図、コンポーネント、SDK、API、および関連ドキュメントのすべてを 1 か所で参照できることです。必要な情報によって、ドキュメントの数が非常に多くなる場合もあります。Atlassian では、これらの情報をすべてテーブルに配置しています。テーブルはページに挿入しやすく、柔軟に使用できます。テーブル ツール メニューを使用して列や行を作成/追加、マージ、セルをハイライトします。



 

オンボーディング コンテンツと同様に、関連アーキテクチャ ドキュメントすべてにラベルを付けて整理できます。

3. リリース プロセスに関するドキュメント

Confluence で作成して保存するもう一つの重要なドキュメント セットは、リリース プロセスおよびリリース予定のドキュメントです。これらのドキュメントは、リリースを整理し、継続的改善を行う文化の構築をサポートします。また、新しい実践方法を導入してプロセスを改善していけるため、進化し続けるドキュメントとも言えます。そのため、全員が最新かつ最高のドキュメントにアクセスできるようにします。これこそが、Confluence が作られた目的です。

 

リリース プロセス ドキュメントの 3 つの重要な要素:

  • 継続的な更新および改善 - 各リリースがチームの学習プロセスになるべきです。開発速度を改善し、リリース待ちの機能をリリースすると同時に、ドキュメントを最新に保つ必要があります。Atlassian では、情報マクロを、ページの関連性を示す視覚的なインジケーターとして使用しています。 
  • 関連ドキュメントの整理 - 関係のあるステークホルダー、潜在的な回避策、およびリリース前後に必要なすべてのコミュニケーションを文書化しましょう。Atlassian では、このような情報すべてに対して個別の子ページを使用しています。これらの関連ページをすべて表示するため、ページの一番上に子ディスプレイ マクロを追加します。このマクロにはホームページのすべてのサブページが表示されるため、必要なページにすぐにアクセスできます。

  • プロセスの視覚化 - Team Calendar は、チームの休日、Jira リリース、およびイベントを一か所で把握するために作られた Confluence のアドオンです。リリース予定ページにカレンダーを組み込み、全員がリリース日を確認できるようするほか、その期間におけるチーム全体の空き状況を確認することで予定の競合を回避できます。月別、週別、またはタイムライン形式で表示できます。

At a glance: what did you just learn?

信頼性に優れたリッチな技術ドキュメントを一元的に用意することは、開発チームにとって魅力的な作業とは呼べないかもしれません。しかし、チームが素早く動き、よいチームから一流のチームへと進化するのに役立つことでしょう。。この記事説明した内容についてまとめます。

This post is part of our latest collection, A Software Team’s Guide to Confluence. Click the lovely green button below to see more.

 

Hungry for more?

Confluence を使用するためのあらゆるヒントを、Confluence を使用するソフトウェア チームのためのガイド ebook をダウンロードしてご確認いただけます。また、このような記事が投稿されたときに通知を受け取るには、このスペースでブログをウォッチしてください。さらに興味がある場合、Confluence に関するすべての情報を網羅する月間ニュースレター、Confluence Insiders へ登録してください。


Powered by Confluence and Scroll Viewport.