Confluence でのデザイン

みなさん、こんにちは！

私の名前はマーシャです。Tinkoff グループ企業で品質保証エンジニアとして働いています。 QA の仕事では、さまざまなチームのさまざまな人々と多くのコミュニケーションが必要ですが、私は教育プログラムのマネージャーや講師も務めていたため、コミュニケーション マップは可能な限り広かったです。 そしてある時点で私は爆発しました。私には、大量の読めない表や書類に記入することはできない、できない、できないことに気づきました。

きっと皆さんは、私が何を言っているのか想像して、冷や汗をかきました。アルファベット順でない姓のリスト、レイアウトが歪んだ何百もの列がある表、指を拭かなければならない何千行もの表。マウスホイールを操作してヘッダー、番号のない指示が書かれた大量のページ、分析と体系化が必要なデータとともに相互に送信される何百通もの手紙が、同様に判読不能な表に詰め込まれていることを確認します。

それで、少し冷静になったので、この記事を書くことにしました。 製品以外のさまざまなドキュメントを通常 (場合によっては便利に) 保守する方法について説明します。 この記事がネット上で拡散され、開発に隣接する部門の地獄レベルが少しでも減り、私も含めた人々が少しでも幸せになれば幸いです。

ツール

製品ドキュメントはコードの隣に置かれることがよくありますが、これは良いことです。 また、製品以外のドキュメントは通常、どこにでも保存されます。 情報をさまざまな場所から Confluence に移動しようとする人はよくいますが、私たちも例外ではありません。 したがって、物語の残りは彼についてです。

一般に、Confluence は高度な Wiki エンジンです。 これにより、書式設定されたテキスト、表、さまざまなグラフなど、さまざまなタイプの表示でデータを操作できます。 これは非常に興味深く強力なツールですが、その準備方法を知らなければ、判読できない文書が再び大量に作成されることになります。 料理を教えてあげるよ！

マクロ

Confluence の魔法のほとんどすべてはマクロから来ています。 マクロはたくさんあり、それらを組み合わせることができます。 有料または無料の場合があります。以下に、マクロのさまざまな例とそのドキュメントへのリンクを示します。

マクロを操作するためのインターフェイスは可能な限りシンプルです。 マクロを追加するには、プラス記号をクリックし、リストから目的の要素を選択する必要があります。

マクロが自己完結型である場合、つまり、マクロ自体の内部に他に何も挿入する必要がない場合、マクロはブロックのように見えます。

マクロが機能するために内部に何かを配置する必要がある場合、マクロはフレームのように見えます。

同時に、ピラミッドにロジックがある限り、XNUMX つのフレーム内に他のものを好きなだけ配置できます。

各マクロにはプレビューがあり、マクロを正しく入力して構成したかどうかがすぐに表示されます。

テンプレート

マクロに加えて、コンテンツを事前に入力するための便利なツールであるテンプレートがあります。
テンプレートは任意のページを作成するときに使用できます。「作成」ボタンの横にある XNUMX つの点をクリックして、目的のテンプレートを選択するだけです。

次に、テンプレート内のすべてのコンテンツが、作成されたページに追加されます。

誰でもテンプレートからページを作成できますが、それを実行できるのは、テンプレート自体を作成または編集する権限を持つ人だけです。 ページの管理方法に関する追加の指示をテンプレートに追加できます。

テーブルの魔法

実際、私は技術者としてテーブルが大好きで、ほとんどすべての情報をテーブルにラップすることができます (ただし、これは常に効果的であるとは限りません)。 テーブル自体は明確で、構造化されており、拡張性があり、魔法のようです。

しかし、テーブルのような素晴らしい存在でさえも台無しになる可能性があります。 そして、それをうまく使用し、さらに改善することもできます。 これについては以下で詳しく説明します。

フィルタリング（有料プラグイン）

巨大で読みにくいテーブルは、フィルタリングを使用すると、サイズを少し小さくして読みやすくすることができます。 これには有料のマクロを使用できます 「テーブルフィルター」.

このマクロ内にテーブルを入れる必要があります (最も醜いものでも可能ですが、重要なことはテーブル全体をプッシュすることです)。 マクロでは、ドロップダウン フィルター、テキスト フィルター、数値フィルター、および日付フィルターの列を選択できます。

すべての求人の候補者に関するすべての情報が表形式のリストに記録されていると想像してください。 当然のことながら、人々は整理されておらず、アルファベット順ではなく面接に来ます。 また、これまでに特定の応募者と面接したことがあるかどうかを理解する必要があります。 この地獄をフィルター マクロに組み込んで、姓によるテキスト フィルターを追加するだけです。これで、情報が画面に表示されます。

巨大なテーブルのフィルタリングはシステムのパフォーマンスとページの読み込み時間に影響を与える可能性があることに注意してください。そのため、巨大なテーブルをフィルタに入れるのは一時的な手段であり、巨大で読み取り不可能なテーブル (プロセスの例は記事の最後にあります)。

並べ替え（有料プラグイン）

マジックマクロを使う 「テーブルフィルター」 任意の列にデフォルトの並べ替えを設定し、行に番号を付けることもできます。 または、フィルター マクロに挿入されたテーブルの列をクリックすると、その列によって並べ替えが行われます。

たとえば、応募者と同じテーブルがあり、特定の月に面接が何回行われたかを推定する必要があります。日付順に並べ替えて満足してください。

ピボットテーブル（有料プラグイン）

次に、より興味深いケースに移りましょう。 テーブルが巨大で、そこから何かを計算する必要があると想像してください。 もちろん、それを Excel にコピーし、必要なものを計算して、データを Confluence にアップロードして戻すこともできます。 一度マクロを使ってみてはいかがでしょうか？ "ピボットテーブル" 同じ結果が得られますが、更新されるだけです。

たとえば、すべての従業員からデータ (従業員が地理的にどこにいて、どのような役職に就いているか) を収集するテーブルがあるとします。 各都市の人口を計算するには、データ (場所) と操作の種類 (追加) を集計するピボットテーブル マクロの行を選択する必要があります。

当然のことながら、一度に複数の基準でグループ化でき、すべての可能性を表示できます。 ドキュメントの中で.

チャート（有料プラグイン）

先ほども言いましたが、誰もが私ほどテーブルを愛しているわけではありません。 残念ながら、ほとんどのマネージャーはそれらをまったく好きではありません。 しかし、誰もが本当に明るい色の図が大好きです。
Confluence の作成者は、このことを確実に知っていました (おそらく、レポートや図表が大好きな上司もいるでしょう。それがなければ、彼らはどうなるでしょうか)。 したがって、マジックマクロを使用できます 「表からのチャート」。 このマクロでは、前の段落のピボット テーブルを配置する必要があります。これで、灰色の退屈なデータが美しく視覚化されます。

当然、このマクロにも設定があります。 マクロのドキュメントへのリンクは、そのマクロの編集モードで見つけることができます。

簡単な集計

前の段落の情報は、おそらくあなたにとって啓示ではなかったでしょう。 しかし、マクロの使用方法は確実に理解できたので、記事のより興味深い部分に進むことができます。

タグ

構造化されていない XNUMX つの記事や巨大なテーブルに情報を保存するのは問題です。 この情報の一部が判読できない形式になっているだけでなく、Confluence 全体に分散している場合はさらに悪いことになります。 幸いなことに、散在する情報を XNUMX か所に集めることができます。 これを行うには、次を使用する必要があります タグ （ソーシャルネットワークで誰もが知っているタグ）。

任意のページに任意の数のタグを追加できます。 タグをクリックすると、そのタグが含まれるすべてのコンテンツと関連タグのセットへのリンクを含む集約ページが表示されます。 関連タグとは、同じページ内で頻繁に表示されるタグのことです。

ページのプロパティ

別の興味深いマクロをページに追加して、情報を構造化することができます。 「ページのプロパティ」。 その中で XNUMX つの列からなるテーブルを送信する必要があります。最初の列はキー、XNUMX 番目の列はプロパティの値になります。 さらに、コンテンツの読み取りを妨げないようにマクロをページから非表示にすることもできますが、ページには必要なキーがマークされたままになります。

ID に注意してください。ID を設定すると、異なるプロパティのグループを異なるページに (または、異なるプロパティのグループを XNUMX つのページに) 割り当てることができます。

レポート

タグを使用してレポートを収集できます。 たとえば、マクロ 「コンテンツレポート」 特定のタグのセットを持つすべてのページを収集します。

しかし、より興味深いレポートはマクロです。 「ページプロパティレポート」。 また、特定のタグのセットを持つすべてのページを収集しますが、単にそれらのリストを表示するだけではなく、列がページである表を作成します (記事の先頭とのつながりがわかりますか?)。プロパティキー。

結果として、さまざまなソースからの情報をまとめた表が作成されます。 アダプティブレイアウト、任意の列によるソートなど便利な機能があるのも嬉しいですね。 また、このようなレポート テーブルはマクロ内で構成することもできます。

構成時に、レポートから一部の列を削除したり、デフォルトの状態や表示されるレコード数を設定したりできます。 ページのプロパティ ID を設定して、必要な情報のみを表示することもできます。

たとえば、従業員ページが多数あるとします。これらのページには、その人に関する一連のプロパティ (その人がどのレベルにいるか、どこにいるか、いつチームに参加したかなど) が含まれています。 これらのプロパティはマークされています ID = 従業員_inf。 同じページには XNUMX 番目のプロパティ セットがあり、チームの一員としてのその人に関する情報 (その人がどのような役割を果たしているか、どのチームに所属しているかなど) が含まれています。 これらのプロパティはマークされています ID = チーム_inf。 その後、レポートをコンパイルするときに、XNUMX つまたは XNUMX つの ID の都合のよい方の情報のみを一度に表示できます。

このアプローチの利点は、誰もが必要な情報テーブルを組み立てることができ、重複するものはなく、メイン ページが更新されるときに更新されることです。 たとえば、チーム リーダーにとって、開発者がいつ仕事に就いたかは重要ではありませんが、各開発者がチーム内でどのような役割を果たしているかは重要です。 チームリーダーはチームに関するレポートを収集します。 そして、会計士は通常、誰がどのような役割を果たしているかを気にしませんが、役職は重要です。会計士は役職に関する報告書を作成します。 この場合、情報源を複製したり譲渡したりすることはありません。

最終工程

命令

そのため、マクロを例として使用すると、Confluence で情報を美しく構造化し、効果的に集約することができます。 しかし、理想的には、新しい情報がすぐに構造化され、すでに使用されているすべての集計メカニズムに組み込まれるようにする必要があります。

ここで、多数のマクロとテンプレートが役に立ちます。 ユーザーに希望の形式で新しいページを作成させるには、テンプレートから作成マクロを使用できます。 ページにボタンを追加し、クリックすると、必要なテンプレートから新しいページが作成されます。 こうすることで、必要な形式ですぐに作業できるようになります。

ページを作成するテンプレートには、ラベル、「ページ プロパティ」マクロ、および必要なプロパティのテーブルを事前に追加する必要があります。 また、ページにどのような値を入力する必要があるか、およびプロパティ値についての指示を追加することをお勧めします。

最終的なプロセスは次のようになります。

1. 特定の種類の情報のテンプレートを作成します。
2. このテンプレートでは、マクロにラベルとページ プロパティを追加します。
3. 任意の便利な場所にボタンを備えたルート ページを作成し、クリックするとテンプレートから子ページが作成されます。
4. ユーザーがルート ページに移動できるようにすると、ユーザーは必要な情報を (ボタンをクリックすることで必要なテンプレートに従って) 生成する可能性があります。
5. テンプレートで指定したタグを使用して、ページのプロパティに関するレポートを収集します。
6. 喜んでください。必要な情報がすべて便利な形式で揃っています。

落とし穴

品質エンジニアとして、世の中に完璧なものなどないと断言できます。 神のテーブルですら不完全です。 そして、上記のプロセスには落とし穴があります。

• ページ プロパティの名前または構成を変更する場合は、既に作成されているすべてのオブジェクトを更新して、それらのデータが概要レポートに正しく含まれるようにする必要があります。 これは悲しいことですが、その一方で、情報セットの「アーキテクチャ」について詳しく考える必要があり、これは非常に興味深い作業です。
• 情報テーブルの記入方法とタグの使用方法について、かなりの量の指示を記述する必要があります。 しかし一方で、この記事を使えば、適切な人全員にヒットすることができます。

製品以外のドキュメントの保存例

上記のプロセスを通じて、ほぼすべての情報のストレージを整理できます。 このアプローチの利点は、普遍的なことです。ユーザーが慣れてしまえば、混乱は生じなくなります。 もう XNUMX つの大きな (ただし無料ではない) 利点は、さまざまな統計をその場で収集し、それらに基づいて美しい図を描画できることです。

チームに関する情報を維持するためのプロセスの例を示しましょう。

私たちはチームの各人に従業員カードを作成することにしました。 したがって、私たちは、新しい各人が自分用にこのカードを作成し、その中にすべての個人情報を保持するためのテンプレートを用意しています。

ご覧のとおり、プロパティの詳細な表があり、このページを正確に保守する方法についての指示がすぐに提供されます。 タグの一部は指示に従って従業員自身が追加します。テンプレートには主要なタグのみが含まれています: カード タグ 従業員カード、方向タグ 方向性が関与する そしてチームタグ チームQA.

その結果、全員が自分用のカードを作成すると、従業員に関する情報を含む完全なテーブルが取得されます。 この情報はさまざまな時点で使用できます。 リソース マネージャーは自分用に一般テーブルを収集でき、チーム リーダーは選択にチーム タグを追加してチーム テーブルを作成できます。

タグごとにさまざまな概要を表示できます。たとえば、 QAアップグレード計画 すべての QA 開発タスクが表示されます。 同時に、各人は重要な履歴と自分自身の能力開発計画を従業員カードに保存し、能力開発計画テンプレートからネストされたページを作成します。

まとめ

ドキュメントは恥ずかしくないように、またユーザーに耐え難い苦痛を与えないような方法で管理してください。

この記事が役に立ち、世界中のすべてのドキュメントに秩序が生まれることを心から願っています。

出所： habr.com