Snykドキュメント：これまでの歩み

過去3年間、Snykユーザードキュメントのマネージャーとして、ユーザードキュメントの数々の改善を監督してきました。

貢献を促す文化

私たちは、ユーザードキュメントに独自の貢献文化を築いてきました。Snykでは何百人ものメンバーが継続的にコンテンツを作成、更新、改善しています。

そのために取り入れた主な方法の一つが、ドキュメントチームでdocs-as-codeのプロセスを採用することです。

Docs-as-code

簡単に言えば、「docs-as-code」とは、執筆プロセスをコード開発プロセスになぞらえ、一般的に開発者に使いやすいプラットフォームやツールを活用することです。たとえば、SnykのドキュメントではGitbookプラットフォームを使用しています。変更にはGitに似た一連のプロセスが適用され、シンプルな編集UIを備え、Markdownファイルで保存されたコンテンツをGitHubリポジトリと同期できます。

このプロセスによって、誰もが貢献できるようになりました。プロ向けの執筆ツールに伴う高い学習コストやアクセス制限をなくすことで、法外なライセンス費用を負担することなく、より多くの人がコンテンツ作成に携われます。

Snykのドキュメント作成方法

Snykでは、新機能のドキュメントの初稿を開発チームがGitBookの執筆環境で作成します。これにより、チームが主体性を持ってコンテンツに関われるため、ほかの情報源から手作業で移行したり書式を整えたりすることなく、すばやく貢献できます。機能がテストに入る前からドキュメントの作成を始めることで、多くの場合、機能がクローズドベータの段階に入る頃にはドキュメントを公開できます。これにより、ユーザーは情報にすばやく簡単にアクセスできます。

私たちはすべての貢献者をトレーニングし、サポートし、参加を促しています。編集画面内でGrammarlyを使った支援を行い、レビューと変更の標準化も徹底しています。新しくR&Dチームに加わったメンバーには、それぞれに合わせたガイダンスと担当ライターを割り当て、貢献方法やサポートの求め方を把握できるようにしています。ドキュメントを効率的に拡大するには、早期の支援と自動化が欠かせません。そのため、Snykのアプローチではこれを重視しています。

簡単に言えば、Snykは次の2つのアプローチを採用しています。

• シフトレフト：リリース直前ではなく、コードを書いている段階から早めにテストする。

• シフトダウン：専門のセキュリティチームではなく、開発者がテストを行う。

私たちのドキュメントプロセスも、同じモデルに沿っています。コラボレーション、拡張性、自動化は、私たちの文化に深く根付いています。

貢献文化の成果

Snykのドキュメント作成方法を変革した結果、2024年初頭の時点で、250人を超えるアクティブな貢献者がいます。また、過去2年間で6,000件を超える変更と改善を行いました。1日あたり約10件にのぼります。

社員は積極的に参加し、技術ライターは機能開発の妨げではなく、推進役として正しく認識されています。機能の説明を直前になって急いで書くこともなくなりました。そうした状況は、リリースの遅延やドキュメントの品質低下、あるいはその両方を招く可能性があります。

取り組み：ユーザー体験、ユーザータイプ、推奨事項

現在は、ドキュメントの品質向上に注力し、Snykのユーザー体験やユーザータイプに合った内容を整えるとともに、より「推奨型」の具体的なコンテンツを提供しています。

ユーザー体験に合わせる

現在、ドキュメントの情報アーキテクチャを刷新しています。これまでは、Snyk製品の使い方を伝える明確な「説明型」ドキュメントを提供してきました。一方で、ベストプラクティスを推奨したり、詳しい例を示したりする「推奨型」ドキュメントはほとんどありませんでした。ドキュメントの構成がユーザー体験、利用の流れ、ペルソナに沿っていなかったため、ユーザーはガイダンスがないまま、自分で導入方法を考える必要がありました。

これまでの構成

こちらが、Snyk製品を中心に構成していた2022年の情報アーキテクチャです。

利用の流れに沿った構成

現在は、ユーザーが順を追って体験する流れに対応した、シンプルで目的に沿った情報アーキテクチャを採用しています。

コンテンツは次の流れで構成されています。

• 最初のセクションでは、クイックスタートで機能を評価し、Snykの導入セクションでビジネスへの導入をより高いレベルで計画するなど、オンボーディングを含むユーザー体験の初期段階を説明します。

• 次に、Snykとのインテグレーションについて説明します。まずGitインテグレーションでソースコード管理リポジトリをSnykに接続し、その後CI/CDインテグレーションで長期的なデプロイ戦略を実現します。

• 続いて、日々のSnykによるスキャンについて説明します。Snyk Open Sourceなど、各Snyk製品の使い方を紹介します。

• Snyk管理セクションでは、一般的な管理タスクを説明します。

• 最後に、独立した2つの領域、CLIとAPIについて説明します。

ユーザータイプに合わせる

ドキュメントを頻繁に利用するSnykユーザーには、開発者、管理者／導入担当者、アプリケーションセキュリティ担当者といったタイプがあることがわかっています。

ユーザータイプごとに必要な情報は異なります。そのため、どのペルソナにとってもドキュメントに簡単にアクセスし、移動できるようにし、それぞれに適したコンテンツ領域を提供したいと考えています。

たとえば、次のように利用できます。

• 開発者：クイックスタートとSnykでスキャンのコンテンツを提供

• 管理者／導入担当者：エンタープライズ構成とSnyk管理に注目

• アプリケーションセキュリティ担当者：リスク管理に注目

推奨型コンテンツの充実

長年にわたって、オンボーディングから日々の利用まで、お客様がSnykをスムーズに導入するための知見を蓄積してきました。この「推奨型」コンテンツには、詳しいユースケース、ステップごとの手順、推奨事項など、実践的な内容が含まれます。これらの知見をまとめ、コンテンツとして公開しています。

このコンテンツは、ユーザーがSnykの利用における各段階を計画するのに役立ちます。また、拡大を続けるエンタープライズ市場では、こうしたコンテンツがさらに求められています。企業が自社のビジネスで効率的なSnykオンボーディングプログラムを実施できるよう、拡張可能で利用しやすいトレーニング資料を提供します。

まずはSnykの導入セクションで、Snyk導入ガイドの作成に着手しました。

今後の取り組み

ドキュメントの改善は、まだ道半ばです。

2024年に向けて、次のような魅力的なドキュメントプロジェクトの企画・準備を進めています。

• お客様がテンプレートとして使える、一貫した「ストーリー仕立て」の要素をドキュメント全体に追加する。

• ユーザー体験に役立つAIを取り入れ、質問への回答をすばやく提示する。

• ユーザー体験により近い場所にコンテンツを組み込み、ヘルプにすばやく、よりスマートにアクセスできるようにする。

• Snykの機能変更をすべて網羅した、一貫性のある詳細な変更履歴を追加する。

• 包括的なエラーメッセージカタログを拡充し、公開する。

詳しくはドキュメントをご覧ください。