ハイテク業界ではテクニカルドキュメントが「おまけ」扱いされがちです。製品に真の価値をもたらす活用法を解説します。
テクニカルドキュメントを価値ある資産に変える
テクニカルライターとして20年以上働いてきた今でも、テクニカルドキュメントの「秘めた可能性」と「現実」のギャップには驚かされます。
ここ数年、ハイテク業界のテクニカルドキュメントを単なる付属物で終わらせず、どうすれば製品そのものに真の価値をもたらせるかを考え続けてきました。
いくつかの製品で実際に試してみたところ、その手応えからこの方向性に確信を持てました。以来、さらにこのアイデアを試す機会を探してきました。DoiTでテクニカルライターとして6か月を過ごした今、これまでに得た学びと新たな気づきを共有したいと思います。
まずは基本から
テクニカルライターは、エンジニアリングチームやプロダクトチームに後から加わるのが通例です(製品開発の進め方をどう捉えるかは組織によりますが)。何しろ今の時代、誰もが書き手であり発信者でもあります。アーリーアダプターを探している段階なら、GitHubリポジトリやブログ記事、フォーラムでの議論の方が、ターゲット層へのリーチに費用対効果が高いこともあります。
製品が初期段階を抜けてスケールするフェーズに入って初めて、テクニカルライターを迎え入れようという話が持ち上がります。私の経験上、そうしたテクニカルライターがまず取り組むべきなのは、コンベンション(規約)に沿った基本ルールを定めることです。
イノベーションや創造性を売りにする業界の話で、最初に「規約」を持ち出すのは違和感があるかもしれません。しかし規約はイノベーションや創造性の敵ではありません。重要でない部分で規約に従えば認知的負荷を減らせ、本当に大切なタスクに集中できるのです。
テクニカルドキュメントの規約には、たとえば包括的なスタイルガイド(Google developer documentation style guide、Microsoft writing style guide)から、シンプルなルール集(AWS document conventions)までさまざまな形があります。
ドキュメント作成を始める前に完璧なスタイルガイドを揃える必要はありません。製品に慣れていく過程で少しずつ作り上げていく方が効果的です。つまり、オンボーディング期間にあわせて進めるのです。
このフェーズで取り組むべきステップは次のとおりです。
- 基本的な整備を進めながら、土台となるルールを固める:
- 見出しやタイトルはセンテンスケースかタイトルケースか。動名詞(-ing)を使うか動詞の原形を使うか。
- 手順は番号付きの箇条書きか、長い文章で書かれているか。
- シリアルカンマに関する厳密なルールはあるか(ライター同士で議論を始めたいときには格好の話題です)。
- UI操作はどう表現しているか。たとえばボタンを「click」「select」「choose」のどれで書くか。
- スクリーンショットの撮り方や見せ方はどうするか。注釈の付け方は?
- 進めながら社内スタイルガイドを構築する:
- 業界標準から良いものを取り入れ、自社のニーズに合わせて調整する。
- これは生きたドキュメントであり、新しい使い方や用語が加わっていくものだと心得る。
社内スタイルガイドはテクニカルドキュメントの根幹です。ライターチームをスケールさせるだけでなく、テクニカルライター向けのドラフトを書く人やブログ記事を書く人など、社内で技術情報を扱うあらゆるメンバーへの指針にもなります。
進めていく中で、より本質的なテーマが見えてくることもあります。たとえば次のようなものです。
- 全体のトーンはどの程度カジュアル/パーソナルにするか。
- 動画はどう活用するか。
- 機密情報はどう扱うか。
- テクニカルドキュメントのステークホルダーや、積極的に貢献してくれるのは誰か。
そこで見えてくるものに、どうか驚かないでください。
テクニカルドキュメントの設計
テクノロジー製品は複雑です。複雑な技術を内部で使っているだけでなく、しばしば他社の製品とも連携します。
テクニカルドキュメントを書くとき、この複雑さにどう向き合えばよいのでしょうか。
よくある答えは「ケースバイケース」から始まります。とはいえ、私たちには強力な武器が2つあります。_フレームワーク_と_コンセプチュアルモデル(概念モデル)_です。
フレームワーク
テクニカルドキュメントにおけるフレームワークとは、個別のトピック(つまり、他のトピックと関連しないトピック)を書く際に役立つテンプレートや概念構造のことです。
ブログ記事やテクニカルドキュメントの個別ページの多くは単一のトピックに焦点を当てているため、明確に定義されたテンプレートやフレームワークの恩恵を大きく受けられます。
インストールガイドを書くときは?
3部構成で考えてみましょう。前提条件(ハードウェアおよびソフトウェア要件を含む)、実行(対象をインストールする実際の手順)、検証(バージョン確認やHello Worldサンプルの実行など)です。
データをクエリする手順をまとめるときは?
必要な権限、クエリの例、入出力の詳細な説明を必ず盛り込みましょう。
テンプレートが用意されていなくても、少し練習を積めばフレームワークは比較的簡単に組み立てられるようになります。DoiT入社前に、私は How to write (and rewrite) というブログ記事を書きました。そこで提案したアプローチは、主にフレームワークの構築に関するものです。
主なポイントは以下のとおりです。
- ミントピラミッド原則(Minto Pyramid Principle®)を使い、複雑な文章の根底にある構造を明らかにする
- ビジュアルヒエラルキーを作り、複雑な内容を読み手が辿りやすくする
- ユーザージャーニーを支える「バケット」を設計する
コンセプチュアルモデル
テクノロジー製品の複雑さの多くは、インタラクションから生まれます。同一製品内のコンポーネント同士、あるいは1つの完成したソリューションを成立させるために連携する、同じビジネス・技術領域の製品同士のインタラクションです。
製品に内在する複雑さを、通常はそのまま外には見せません。あなたの「秘伝のソース」は競合の関心は引いても、顧客にとってはそうとは限らないからです。
本当に注意すべきは、外部との摩擦を生む複雑さです。それこそが顧客を、ときには自社のサポートチームさえもつまずかせる元凶になりがちです。
名著 The Design of Everyday Things の中で、ドナルド・ノーマンは「複雑さを飼いならすうえで最も重要な原則は、優れたコンセプチュアルモデルを提供することだ」と述べています。私も心から同感です。
では、テクニカルドキュメントでコンセプチュアルモデルをどう活かすのか。DoiT Help Centerから2つの例を取り上げて見ていきましょう。
ビルディングブロック型の機能
Attributions機能について、DoiTのプロダクトマーケティングマネージャーであるMatan Bordoは「使いこなせれば、DoiT Cloud Intelligence™の中でも特に手放せなくなる機能のひとつ」とよく口にします。「使いこなすのは簡単じゃない」と感じているなら、その気持ちはよくわかります。
Attributionsはビルディングブロック型の機能です。他の多くのビルディングブロックと同様、それ単体ではほとんど何も生みません。しかし、本質をつかめば使いこなすのが楽しくなります。
最近のアップデートでは、この機能のドキュメントを見直し、細かな設定の話に入る前にまず「何ができるのか」をユーザーに掴んでもらえるよう、ユースケースを冒頭に配置しました。
エコシステムとの連携機能
9月には、Visualize with Grafana Cloud という記事を追加しました(CTO兼共同創業者のVadim Solovey寄稿)。ご存じのとおり、GrafanaはDoiTのソリューションではなく、Cloud Native Landscapeでも広く知られた人気のサービスです。
ビルディングブロック型機能の例と同様、Introductionではこの統合の狙いと、クラウド上でビジネスを展開する企業にとってどのようなメリットがあるのかを明確にしました。
製品内であれエコシステム内であれ、優れたコンセプチュアルモデルは相互作用するコンポーネント間の関係を描き出し、ユーザーが選んだ領域を辿る道しるべになります。
ほかにもメリットは? テクノロジーについて確実に言えるのは、ユーザーは課題解決のために技術を使うとき、驚くほど創造的だということです。適切なコンセプチュアルモデルがあれば、ユーザー自身が製品のユースケースを次々と見つけ出し、さらには自発的なエバンジェリストとなって、製品をより良くする手助けまでしてくれるでしょう。
これはチームワーク
さて、ここまでで何が見えてきたでしょうか。
規約やフレームワークは、汎用的なテクニカルライティングの知識で対応できます(だからこそ、新入社員やジュニアライターにとって良い出発点になります)。一方、各レベルで適切なコンセプチュアルモデルを構築するには、製品に対する深い知識が欠かせません。
DoiTは、深いクラウドの専門知識と顧客中心の姿勢を誇るテクノロジー企業です。学びの環境は申し分ありません。社内Slackチャンネルでの議論や、社内Wiki・StackOverflowで共有される情報は知見にあふれ、メンバーは自分の知識を惜しみなく共有し、互いに助け合い、個人としても組織としても成長するために協力し合っています。
多分野で構成されるプロダクトマネジメントチームの一員として、テクニカルライターはプロダクトマネージャーやデザイナーにとっての「思考のパートナー」でもあります。明確に書く力は、明確に考える力に支えられています。これは前提条件を浮き彫りにし、製品機能をモデル化するうえで大きな価値を発揮します。
テクニカルライティングチームが目指す姿を議論するなかで、私たちは「テクニカルドキュメントをDoiTのプロダクトportfolioにおける価値ある資産にする」というビジョンを掲げました。鍵となるのはチームワークです。質の高いテクニカルドキュメントは、テクニカルライターだけの孤独な仕事ではなく、DoiTのテクニカルライティングチームが先頭に立ち、組織全体と協働しながら届けていく取り組みなのです。