技術的な専門知識を必要とせずに、製品ドキュメント作成プロセスを効率化したいとお考えですか？Apidogは、プロダクトマネージャーと運用チームが、プロフェッショナルなドキュメントの作成、管理、公開においてシームレスに協力できるように支援する包括的なソリューションを提供します。直感的なインターフェース、リアルタイムのコラボレーション機能、ゼロメンテナンスの公開機能により、Apidogはチームのドキュメントワークフローへのアプローチを変革します。
すべての製品には独自のドキュメントが必要です。たとえ製品が非常に直感的でシンプルなインタラクションデザインを持つ消費者向けアプリケーションであっても、さらなる説明が必要な領域は存在し、それらを製品インターフェースに直接表示すると複雑さが増してしまいます。したがって、ドキュメントの管理、保守、公開は、すべての製品にとって極めて重要な課題です。
製品ドキュメントを構築する際、チームは通常、Notionのような既成のドキュメントツール、ConfluenceやCMSのようなコンテンツ管理ツール、DocusaurusやGitbookのようなドキュメントジェネレーターを使用します。しかし、これらのソリューションはしばしば以下の問題に直面します。
- **ドキュメントの作成にはコーディングが必要**で、コストが高い。ドキュメントが作成された後でも、実際の閲覧体験は期待を下回ることがよくあります。
- **ドキュメントは複数の役割が共同で作成する**ため、バージョン管理が困難であり、最適化の提案を他者に伝えることが難しくなります。
- **完成したドキュメントを本番環境に公開するプロセスが、単純すぎるか複雑すぎるかのどちらか**で、非技術系の同僚が対応するのが難しいエンジニアリングプロセスを伴う可能性があり、エラーにつながります。
Apidogチームは以前、Docusaurusを使用してドキュメントを作成していました。ドキュメントの反復が続くにつれて、上記で述べた問題のいくつかに直面しました。私たちの経験と学んだ教訓をまとめた後、解決策を開発し、それらをApidogに統合しました。現在、**Apidogチームの製品ドキュメントは完全にApidogに移行されており、すべての作成と表示はApidogによって処理されています**。
Apidogを通じて製品ドキュメントを構築する方法について、私たちの実践を共有します。その前に、Apidogの製品ドキュメントの具体的な効果を詳しくご覧になりたい場合は、Apidogのヘルプドキュメントをご確認ください。フィードバックも歓迎です。
背景
私たちの実践を紹介する前に、なぜ私たちがこのように行うのかを皆さんがよりよく理解できるように、まず説明する必要があるいくつかの背景があります。当社の製品ドキュメントは、通常、**製品部門と運用部門の同僚によって共同で作成されます**。主なプロセスは以下の通りです。
上記のプロセスは、技術者の関与を必要としません。すべての製品ドキュメント関連の操作は、これら2つの部門の同僚によって完了されます。次に、このプロセスに従ってApidogを通じて製品ドキュメントを構築するタスクを完了する方法を説明します。
コアプロセス
1. コンテンツ管理とコラボレーションのためのスプリントブランチを作成する
開発イテレーションが開始された後、運用部門の同僚はApidogにイテレーションブランチを作成し、現在のイテレーションにおける変更を含むすべてのドキュメントをこのブランチ内に配置して共同作業を行い、メインブランチへの直接的な影響を回避します。
作成後、プロダクトマネージャーは、イテレーションで実際に更新された機能に基づいて、変更が必要な既存のドキュメントをこのイテレーションブランチにインポートし、新機能の新しいドキュメントをイテレーションブランチに直接作成します。ここでの操作は、APIドキュメントのイテレーションブランチの使用法と完全に一致しています。
メインブランチに保護を設定しているため、メインブランチ内のドキュメントコンテンツを直接変更することは許可されていません。これは、ユーザーが直接閲覧できる公開済みドキュメントのコンテンツを手動で変更できないことを意味し、製品ドキュメントをより安定させ、ランダムな変更がユーザーに誤ったコンテンツが表示される状況を減らします。
2. 美しいMarkdownエディタを使用して各ドキュメントを作成する
プロダクトマネージャーは、イテレーションブランチ内で現在のイテレーションで更新する必要があるドキュメントをMarkdownで作成します。ApidogのMarkdown機能は非常に強力で、様々なビジュアルコンポーネントをクリックするだけで、多くの複雑なスタイルを簡単に挿入でき、少ない労力で美しい記事を簡単に作成できます。
一般的なMDスタイルのビジュアル挿入に加えて、Apidogは以下の特別な機能を追加しました。
- **プロジェクトAPI/ドキュメントの挿入**。ドキュメントが相互にリンクして参照チェーンを形成し、シームレスなナビゲーションを可能にすることで、読者にスムーズな体験を提供し、読者のニーズと問題をよりよく解決します。これは非常に重要な機能です。
- **アイコン、ハイライトブロック、テーブル、ステップ、Mermaid、ビデオなど、豊富なリソース挿入機能を提供**。そのため、自分でリソースを探したり、ドキュメントをより良く見せるためにMDスタイルの構文を学ぶ時間を費やす必要がありません。
3. 製品/運用部門の同僚が協力してドキュメントを磨き上げる
プロダクトマネージャーがイテレーションブランチでドキュメントの初期バージョンを作成した後、ドキュメントの品質、明瞭さ、ユーザーへの有用性を向上させるため、運用部門の同僚にドキュメントを渡し、ユーザーの視点から読んで修正提案を提供してもらい、磨き上げます。
これはかつて、**最も時間と労力がかかる**部分でした。双方が相互に協力し、一方が自分のアイデアを説明し、特定の箇所について具体的な修正提案を行い、もう一方がそれを受け取り、理解し、実際に変更を加える必要がありました。このやり取りの過程で、誤解、誤った変更、ドキュメントのバージョン間の内容の相違など、様々な問題が頻繁に発生し、効率が非常に低くなっていました。
現在、Apidogを使用すると、双方がドキュメント内で直接変更を加えることができ、変更が行われるとリアルタイムのメッセージ通知がIMにプッシュされ、他の人がすぐにドキュメントに入って特定の変更を簡単に確認できるため、コラボレーションの効率が大幅に向上します。具体的な手順は以下の通りです。
- プロダクトマネージャーがドキュメントの初期バージョンを作成します。運用担当者は通知を見た後、ドキュメントを読み、**このドキュメント内で変更したい内容を直接修正します**。
- 変更は保存時に自動的に通知をトリガーし、変更メッセージカードを事前に設定されたIMグループに送信します。グループメンバーは変更概要メッセージカードを見た後、通知リンクをクリックしてワンクリックで関連ドキュメントに入ることができます。
- **変更履歴を通じて**、現在のバージョンと元のバージョンを選択して差分を比較し、相手の修正を簡単に確認してドキュメントをどのように調整するかを決定できます。提案を受け入れずに元のバージョンに戻すことも、修正を受け入れて最新バージョンを維持することもできます。
製品チームと運用チームは、ドキュメントのコンテンツが磨き上げられ、全員が承認するバージョンが決定されるまで、上記の手順を繰り返します。
4. 公式ドキュメント公開前の準備とレビュー
ドキュメント内のコンテンツと製品スクリーンショットが、ユーザーがアクセスできるものと完全に一致していることを確認するため、製品の本番環境でスクリーンショットを撮ることをお勧めします。これにより、本番環境でリリースされた新機能が正しく動作しているかどうかも検証できます。運用担当者は、新機能をオンラインで使用してスクリーンショットを撮った後、それらを記事に追加します。
運用担当者は、このイテレーションで完成したコンテンツドキュメントを確認し、それらを選択して、メインブランチにマージするためのMRリクエストを提出します。
運用マネージャーまたは他のプロジェクト管理者は、公開されるドキュメントコンテンツをレビューし、それが正しいことを確認した後、メインブランチへのマージを選択します。
マージが完了した後、ユーザーが公開されたドキュメントにアクセスすると、メインブランチにマージされた最新のコンテンツを見ることができます。
その他の利点
すでに紹介した機能に加えて、Apidogには、よりニーズに合った製品ドキュメントサイトを構築するのに役立つ、ドキュメント公開に関する以下の機能もあります。
1. 製品/企業スタイルに合わせた全体的なドキュメントサイトスタイルを設定する
公開されたドキュメントサイトの全体的なスタイルを設定でき、ウェブサイト全体のスタイルを会社のトーンにより合わせることができます。また、関連リソースや会社のコンテンツリンクをさらに追加して、ユーザーにより良い体験を提供できます。
Apidogのヘルプドキュメントには、独自のロゴとApidog関連のリソースリンクが設定されています。左上には会社のロゴが、右上には様々な会社関連のリソースリンクがあり、開発者がより関心を持つ公開APIドキュメントも製品ドキュメント内に設定されています。
2. ゼロメンテナンスの公開体験
Apidogでは、ドキュメント公開機能の「公開」ボタンをクリックするだけで、ドキュメント全体をワンクリックでインターネットに公開し、ユーザーが閲覧できるようにすることができます。Apidogは公式に誰もが使用できるドメインを提供しており、多くのメンテナンス作業を削減します。
もちろん、ドキュメントを自社のウェブサイトのようにより見せたい場合は、カスタムドメイン機能も提供しており、自社のドメインを使用してドキュメントにアクセスできます。
公開された製品ドキュメントサイトでは、簡単な操作で通常の検索、Algolia全文検索、GA統合、リダイレクト設定など、その他の高度な機能を簡単に設定できます。これらの設定には、運用者が十分なエンジニアリング能力を持つ必要はなく、インターフェースのガイダンスとヘルプドキュメントに従うことで簡単に設定できます。
3. 複数のSEOフレンドリーな設定
Apidogは、公開されたドキュメントサイトの基本設定に基づいて、ユーザーがよりアクセスしやすく共有しやすいように、合理的なスラッグを自動的に生成します。
もちろん、より高度なSEOニーズがある場合は、各ドキュメントのカスタムスラッグ、メタデータ、およびその他の様々なコンテンツ設定もサポートしています。
結論
以上が、Apidogを使用した製品ドキュメント保守の具体的な実践です。
上記の内容に加えて、製品ヘルプドキュメント、開発者ドキュメント、APIドキュメントをすべて一貫したスタイルで維持し、相互にリンクさせることで、さらに優れたユーザー体験を提供できます。あなたの実際の状況が適切であれば、この実践を試して他の同僚にも推薦してください。これがあなたの製品ドキュメント構築作業に、ある程度の効率と品質の向上をもたらすことを願っています。