こんにちは。CLOVA技術ドキュメントの作成・管理を担当しているTechnical WritingチームのJeongil Kangです。
私がテクニカルライティング(Technical writing)分野に携わってから、もう10年くらいになります。しかし、この記事をお読みの方の中には、テクニカルライティングという言葉を初めて聞くか、聞いたことがあっても果たしてどのような仕事なのかピンとこない、という方も多くいらっしゃるかも知れません。
韓国でも、大学にテクニカルライティング関連学科がないからか、この分野に携わる方はなかなか見当たらないのが現状です。特に韓国ではソフトウェア産業の特性から、設計ドキュメント、APIレファレンスといった技術ドキュメントを扱うテクニカルライターに出会うというのはなかなか難しいことです。
こうした厳しい環境においてテクニカルライターの多くは、業界の最新ニュースや仕事に関わる知識、戦略を手に入れるためにネット検索かチームメンバー同士の情報・経験の共有に頼っています。
ところが今回のWrite the Docsカンファレンス参加で、普段抱えていたそうしたニーズもだいぶ満たされたような気がします。今日はそこで見聞きしたことをブログ記事で皆さんに共有したいと思います。「Learning to love release notes」セッションはリリースノートの書き方について語られていたもので、テクニカルライターのみならず開発者にも有効な内容となっています。
Write the Docsの概要
Write the Docs(以下、WTD)は、コミュニケーション、ドキュメント、そしてユーザ研究から得られた知見を共有するためのコミュニティとして、特にソフトウェア産業やその関連分野にフォーカスしています。同コミュニティによるWTDカンファレンスは毎年春は米ポートランドで、秋にはチェコのプラハで開催されます。そこに集まった参加者たちは会場で各自ドキュメントやプロジェクト管理から得た経験を共有し、興味深いテーマについてはディスカッションもしながら、人を紹介され、新しいニュースを入手します。ちなみに、Serizawa Susaさんは2018年4月にパリで行われたAPI the Docsカンファレンスに参加し、API the Docs参加レポートと題した記事を投稿しています。そこに紹介されたAPI the Docsは、WTDカンファレンスの影響を受けて行われるカンファレンスシリーズです。ご興味のある方はSerizawa Susaさんの参加レポートを合わせてお読みいただくことをおすすめします。
今回私が参加したカンファレンスの正式名称は「Write the Docs Prague 2018」です。チェコ・プラハ市内のAutoklubで9月9日から3日間にわたって開催されました。今大会で行われたプログラムは以下のとおりです。
- Writing day, Reception(9/9)
- Conference talk(9/10~9/11)
- Unconference and light talks
当日の会場の様子をお届けしたくて写真も何枚か用意しました。
以下、メインホールと発表中の様子です。
メインホールの向かい側の会場では、特定のテーマについて語り合う、いわゆる「アンカンファレンス(Unconference)」というプログラムが実施されました。下の写真から、アンカンファレンスで扱われたテーマをご確認いただけます。
今回の記事では、もっとも記憶に残る二つのセッションと、各セッションについての私の感想をお伝えしていきます。
Tackling technical debt in the docs
このセッションでは、英Sage社でテクニカルライターを務めるLouise Fahey氏から、文書化プロジェクトにおける技術的負債(technical debt)の概念と、それをいかに見つけ、除去するかについて氏の経験を交えて語ってもらいました。
技術的負債とは？
技術的負債という言葉については、ソフトウェア開発分野に限られた用語、という認識があるようですが、同セッションでLouise氏はソフトウェア開発プロジェクトと文書化プロジェクトを特に区別することなく、技術的負債について以下のように定義しています。
技術的負債とは、プロジェクトが直面した問題に対し、長期的な観点から企画・検討せずに行き当たりばったりな対応をしたことで、後から大きなコストが生じかねないことを意味します。Louise氏はアジャイル開発プロセスの声明書作成メンバーの1人であるWard Cunninghamの言葉を引用し、「重要な部分を先送りにすること」と、さらに短く表現しています。
Louise氏は、文書化プロジェクトにおける技術的負債はlack of skillとlack of standardによって発生すると言っています。文書化プロジェクトでドキュメントの作成・管理に利用されるツールや技術はジェネレーションアップとともにどんどん変わっていきますが、そのとき、不要になったコンテンツ、画像、スタイル関連ファイルが残ってしまうことがあります。Lack of skillは、これらのリソースやそれによってもたらされる文書化作業の停滞、管理しにくくなる現象を指します。一方でlack of standardは、ドキュメント作成やレビューに必要なスタイルガイド、テンプレートが確保できず、長い間手付かずの状態となり、結果、ドキュメントの整合性やクオリティに影響を及ぼしてしまうことを意味します。
技術的負債への気づき方
技術的負債に気づく方法には色々ありますが、文書化プロジェクトでは次のようなシグナルに注目する必要があるそうです。
- ドキュメントのビルドがどんどん遅くなっている。
- 使用しないコンテンツファイル、画像、スタイルがある。
- 開かないリンク先やブックマークがある。
- ローカライゼーション作業に、コンテンツ翻訳と関係ない問題が発生している。
技術的負債への対応
ソフトウェア同様、ドキュメントにおいてもこうした負債をほったらかしにすると、解決コストは見る見る膨らみ、結果としてドキュメントのクオリティを低下させてしまうそうです。そんなことにならないよう、事前に手を打っておくことで技術的負債を減らすことが重要とのことでした。以下、その方法です。
- 技術的負債には何があるかを把握し、書き並べてみる。
- 洗い出された技術的負債を分類する。
- それぞれの負債解消にかかるコストを割り出す。
- 負債に優先順位をつける。(至急対応すべきか？重要なことなのか？読者から繰り返し求められていることなのか？)
- 負債解決で得られる利益を把握する(負債解決の正当性が確保される)。
- 負債解決の時間を確保する。
- 負債を解決したら、改善結果を測定・共有する。
上記の取り組みを繰り返し行うことによって技術的負債が解消または問題にならないような状態に達したとしても、そうした状態を引き続き維持するには以下の取り組みがさらに必要となります。
- 随時、あるいは定期的にプロジェクトを検討(audit)する。
- スタイルガイドやテンプレートを作成し、こまめにアップデートする。(Lack of standardの解決は技術的負債のない状態を維持するうえで役立つ)
- ユーザの声を随時聞いて反映する。
- Definition of Doneを定義する。(DODは文書化作業のクオリティを保証するツールとして利用できる)
感想
ドキュメントにおける技術的負債については、Heuiseung LeeさんがA社内プロジェクト「Armeria」をオープンソース化するために行った６つのステップで「文書化負債(documentation debt)」と称して先に取り上げています。私はその記事を読むまで、「負債」という言葉が「ソフトウェア開発」プロジェクトには関係あるけど、「ドキュメント」プロジェクトとも関係があるとは思っていませんでした。それで今回のWTDカンファレンスの発表テーマが公表され、本セッションのタイトルを目にしたときは、「一体どんな話になるのか」ととても気になったものです。そうして出席したセッションで、私は文書化プロジェクトに対する新たな考え方に気づいたのです。それは、ソフトウェアでもドキュメントでも、何らかのコンテンツを作り上げるのに「プロセスとコスト」がかかる以上、それに付随する「負債」という概念はどうしても生じてしまうということでした。さらに、詳細なところでは違うかも知れませんが、プロジェクトとして進めるからには文書化プロジェクトにもソフトウェア開発の方法論などを取り入れることは可能と気づいたわけです。
今の私は通常の仕事に復帰し、これまで貯まった負債の返済(?)に勤しんでいます。CLOVA技術ドキュメント・リポジトリのリソースファイルを改めて確認したり、最近盛んに行われているローカライゼーション作業のときに不要なコストが発生しないよう、スクリプトを作成し、情報構造も再構築しています。文書化プロジェクトで技術的負債がこれ以上膨らむことがないように、スタイルガイドやテンプレートを取り備えておくなど、長期的な観点からも取り組んでいます。
Learning to love release notes
こちらのセッションは、開発者の方にもかなり役立ちそうな内容でした。セッションが始まると、イギリスのスタートアップ企業のImprobable社でテクニカルライターを務めるAnne Edwards氏がリリースノートの書き方についていくつかのコツを共有してくれました。
リリースノートとは？
Anne氏は冒頭で、個人的に考えるリリースノートの定義についてまず述べています。その概念は以下のとおりです。
- ソフトウェアリリースとともに掲載される箇条書き(bullet list)の文章
- Bug fixes、New features、Known issuesの項目からなる
- 情報提供はコンパクトかつ簡潔
- ぎりぎりになってものすごい勢いでまとめた情報(発表者の私見でしたが、私はこの定義にとても納得しました)
リリースノートの構成要素
続いて、リリースノートの構成要素であるBug fixes、New features、Known issuesについても次のように定義しています。
- Bug fixes: 持続的に発生してユーザの使い勝手を悪くしたエラーやバグなどの修正
- Features: 持続的にあるいは長い間、ユーザから要求があって追加したもの
- Known issues: ときどきあるいはたまに発生するエラーや不具合(まだ直せていないか、直し方が分からない)の情報。さらに、それらをいずれ修正するという告知。
リリースノートが書きにくい理由
Anne氏は自身の採用面接のとき、「今の仕事で楽しめてないのは何か」という質問に「リリースノートの作成」と答えた話をすると、次のような理由を上げてリリースノート作成の大変さを述べています。
- 互いに関連性の低い項目が書き並べられる。
- よって、他のドキュメントに比べ、コンテキストスイッチ(Context switching)が頻繁に発生する。
- 項目ごとに調べるものもたくさんある。
- 簡潔、それでいて多くの情報を的確に伝えることが求められる。(簡潔な文章とたくさんの情報を含む文章は相反するところがあって、両方をとるのは難しい)
- コンテキストの流れがないため、他のドキュメントに比べて書くこと自体があまり楽しくない。
リリースノート作成のコツ
Anne氏は自らの経験を活かし、リリースノートをきちんと作成するために押さえておきたいコツをいくつか紹介してくれました。
まず一つ目に、「リリースノート作成の際は'Expand out and Simplify'戦略を駆使すること」。リリースノートを最初から簡潔に書こうとすると、入れるべき情報が抜けていたり、曖昧な文章になってしまうということでした。それに対してAnne氏の推奨する戦略は、始めは文章がやや長くなってもとにかく入れるべき情報をちゃんと盛り込むことに集中し(Expand out)、その後からあまり重要でない部分、補足の部分をそぎ落とし簡潔化(Simplify)していくものです。
二つ目は「ユーザ目線で書くこと」です。例えばシステムにモジュールAが追加されたとします。'システムにモジュールAを追加'といった具合に、システム側の観点からリリースノートを書くのはよくあることですね。Anne氏は「××機能(モジュールA)が利用できるようになった」のように、モジュールAが追加されたことでユーザ、またはユーザのワークフローがどのような影響を受けるかというところにフォーカスして書くことを推奨しています。
最後に、「書く人のユーモアや個性が現れるような書き方は控えること」です。親しみやすさを出そうとするとダラダラとした文章になりがちなものです。すると読者は、必要な情報を求め、さらなる認知活動を行わねばなりません。ユーモラスな表現、砕けた表現は、読み手によって受け止め方が違うこともあるので注意が必要です。そうした表現には作成者の個性が現れるものですが、それは会社やサービス、プロダクトを説明するような文面にはふさわしくないと話しています。
続いてAnne氏は、作成者はリリースノートが簡単に作成でき、読者は情報を素早くキャッチできるよう、テンプレートを使用することを推奨しながら以下の3つのテンプレートを提供してくれました。
| 英語表現 | 日本語表現 | 説明 |
|---|---|---|
| You can now ... | ...ができる。...が可能になる。 | Bug fixes項目、Feature項目に使えるパターン |
| X now/no longer does Y when Z. | Zのとき、YせずにXをする。 | 過去(Y)と現在(X)の違いを説明し、コンテキスト(Z)を表したいときに有効なパターン |
| X now/no longer does Y. This means you no longer /now need to do Z. | Zするために、Yの代わりにXをする。 | 過去(Y)の代わりに現在(X)を行って目標(Z)が達成できるようにガイドしたいときに有効なパターン。ユーザにワークフローのアップデートをガイドするときに有効。 |
サマリー
以下、本セッションの内容を表にまとめたものです。
| 従う点 |
|
|---|---|
| 控える点 |
|
| 作成のコツ |
|
感想
このセッションを聞いて、テクニカルライターである私自身もまだリリースノートがきちんと書けていないことに気づき、深く反省したものです。リリースノート作成における発表者の知見の深さに感心する一方で、リリースノートの定義についても改めて考えさせられるきっかけになりました。今自分が担当している文書化プロジェクトのみならず、これから作成していくリリースノートにもこうした内容を何とかうまく取り入れていきたいと思います。(もっとも、Anne氏が共有してくれたテンプレートは、各言語の特性に合わせて少し調整する必要はありますが) リリースノートと関連したスタイルガイドやテンプレートもきちんと確立し、これから技術的負債が積み重なっていかないよう(増えるとしても極力押さえられるよう)取り組んでいく考えです。
おわりに
WTDカンファレンスは上記だけでなく他のセッションでも、テクニカルライティング業務を行う上で役立ちそうな様々な情報を提供しています。そしてそれらの情報について他の参加者と意見交換できるよいきっかけも提供されました。このような機会に恵まれたのは会社や仲間たちのお陰です。今後、WTDカンファレンスで得た情報やノウハウを積極的に共有し、仕事に生かしていきたいと思います。
最後に、今回のカンファレンス参加で気づいたコツをもう一つご紹介しましょう。メインプログラムだけでなく、レセプションプログラムも重要だということです。多くの場合カンファレンス会場はヨーロッパや北米地域にあり、韓国から行くとなると長時間移動することになります。結果、長い飛行時間と時差ぼけのためかなり疲れた状態で到着してしまいます。肝心なメインプログラムに集中するためにはしっかりした体調管理が必要で、私は普通、メインプログラムの前日夜に行われる前夜祭などレセプションプログラムはスキップし、早めに睡眠をとったものです。(昔の仲間など周りの人に聞いてみても、メインプログラムにのみ集中するか、スポンサーブースを見て回るくらいにしているらしいです)
ところが今回は何となくレセプションに行ってみたいと思ったので、思い切って参加することにしたわけです。このことはそれまで私が抱いていたカンファレンスに対する認識をずいぶん変えてくれました。メインプログラム前日に3時間ほど続いたレセプションプログラムで多くの方とお会いし、うち何人かとはとても打ち解けた会話ができました。もちろん、WTDカンファレンスが基本方針として参加者同士の交流を強調しているのもあります。とにかくレセプションに出席した甲斐あって、私はメインプログラムが行われる間もレセプションで親しくなった参加者と一緒にセッションで聞いた内容を共有したり議論したりしながら、お互いの経験や戦略などについても意見を交わすことができました。普通、このようなカンファレンスは一人で行くことが多く、大会期間中ずっと一人浮いているという感覚があったのですが、今回はカンファレンスを存分に楽しむことができました。食事をしたり、提供される飲み物やスナック菓子をつまみながらも、仲良くなった人たちとの会話は途切れることがなく、寂しい(?)思いをせずに過ごせました。
実をいうと、これまではカンファレンスに行っても何となく落ち着かず他の参加者と会話するのが苦手だったのですが、最初それは自分の外国語能力や少し目立つ外見のせいだとばかり思い込んでいました。ところが、そうではなかったのです。もし私と同じようなパターンでカンファレンスに参加されている方は、今度はぜひメインプログラム前に行われるレセプションプログラムにも参加し、少なくとも2~3人の参加者と連絡しあう関係をつくってみるのはいかがでしょうか。きっと愉快な経験になるはずです。