エンジニアが作成したドキュメントでよくある間違いとその修正方法

過去 6 か月間、私たちの開発チームは「docs-as-code」アプローチを採用してきました (私たちの取り組みについて詳しくは、こちらをご覧ください) 記事）。技術部門の同僚が作成したドキュメントを定期的に確認し、技術ドキュメントを作成する際に発生する最も一般的な問題のリストをまとめました。

この記事では、「docs-as-code」アプローチのツールを使用してこれらの問題を解決する方法を説明します。

問題 1. 「ドキュメントの作成は私たちの責任ではありません」

アドホックにドキュメントを扱うことは、開発チーム全体の足を撃つようなものです。チームに能力が不足している場合、ドキュメントの保守をテクノロジー主導で予測可能にすることが説得力のある理由になります。

修理：

• 「docs-as-code」アプローチをドキュメントの開発に統合します。こうすることで、技術的負債が蓄積するリスクを負うことなく、コードベースと並行してドキュメントを繰り返し更新できます。
• 技術ドキュメントを表示し、単一の情報源として機能するスペースまたはプラットフォームを開発または統合します。
• 統合開発環境 (IDE) を利用します。 IDE を使用すると、プラグインを組み込み、ドキュメント開発用のカスタム スクリプトを作成できます。アイディアはドキュメント作成に最適なツールですが、アプリケーションの中にはお気に入りがあるかもしれません。
• タイプミスを防ぐためにスペルチェック プラグインをインストールします。プラグインを IDE に追加するプロセスは迅速かつ簡単です。
• テクニカル ライティング コミュニティ (存在する場合) からの洞察を考慮して、会社が特別に作成した内部ガイドラインを採用し、社内でドキュメントを作成するための標準化されたアプローチを確立します。これらのガイドラインに従うと、文書化プロセスが合理化され、何をどのように正確に書くかを検討する時間が節約されます。
• ガイドラインに基づいてチェックを自動化し、ドキュメントのレビューにかかる時間を大幅に短縮または排除します。
• 可能な限りすべてをテンプレート化し、ドキュメントコンポーネントの標準化についてチームと合意します。

技術文書を扱う際の自信を高める貴重なリソースを提供します。これらのリソースは、技術ドキュメントを効果的に処理するための十分な包括性を備えていると思います。

• 」 Google デベロッパー ドキュメント スタイル ガイド" は、開発者向けドキュメントの包括的なハンドブックとして機能します。このガイドには、書式設定、句読点、リスト、コード ブロックの追加について知っておくべきことがすべて記載されています。このガイドは十分であり、内部ガイドラインを作成するための貴重な参考資料となっています。ベストプラクティス。
• 「開発者向けドキュメント" は、開発者向けドキュメントの開発、執筆、保守など、開発者向けドキュメントの取り扱いに携わるすべての人にとって必読の本です。この本には、テクニカル ライティングの分野で著名な著者が数名登場しています。

• 」コードのようなドキュメントテクニカル ライターの Anne Gentle による「」は、OpenStack のドキュメント文化を紹介する実践的なガイドです。著者は、実践的な例を通じて、ドキュメントを GitHub で管理する必要がある理由と、効果的なドキュメントを作成するための技術プロセスの実装方法を説明しています。また、この本は貴重な情報を提供しています。開発者かテクニカル ライターかを問わず、専門的なドキュメントの作成に関する洞察を得ることができます。

• また、技術文書を作成するための内部ガイドラインにも触れます。これには、テンプレートとフォーマット規則が含まれます。このようなガイドラインはどの企業にも存在します。通常、これらはテクニカル ライターの先駆者や開発ドキュメントの擁護者と協力して開発され、チーム内のドキュメント文化が成長するにつれて進化します。

問題 2. ドキュメントを一人で書く

ドキュメント全体を単独で作成し、それをレビューのために提出すると、意図した目的と一致しない冗長なドキュメントや無関係なドキュメントが作成されるリスクが伴います。

修理：

• 常に概要から始めて、チームリーダー、製品所有者、テクニカルライター、または専門家の意見を提供してくれる同僚とそれを共有してください。
• ステップバイステップで作成し、上記と同じ同僚にレビュー用のプル リクエストを割り当てます。
• フィードバックを収集して取り組みます。
• コメントを考慮してください。レビューの口調については、落ち着いて考えてください。時には厳しい場合もありますが、それはレビュー プロセスの特殊性に過ぎません。
• 文書化の流れを見逃さないでください。以下は当社で採用されている一般的なフローですが、このフローの特徴は開発チームや会社によって異なる場合があります。

課題3.「理解すべき人は理解する」

時折、チームから「私は開発チームのために書いている」、「理解する必要がある人は理解できるだろう」、「これが私たちのチーム内で歴史的にどのように進化してきたか」という言葉を聞きます。

ただし、専門用語や英国英語には適切さと一貫性が必要です。これらを過度に使用すると、狂ったエンジニアのメモのような文書が作成される可能性があります。

文書化には、できるだけ単純な単語と構造を使用してください。主な原則の 1 つは、スクロールするために書くことです。ドキュメントは長大なことが多いため、書くのが難しい場合がありますが、読者が最初から最後まで読むことはほとんどありません。代わりに、スクロールしたりキーワード検索を使用したりする傾向があります。したがって、文章はどの部分から開いても理解しやすいものでなければなりません。

修理：

• 辞書や現在の標準を使用して (または単純に Google で) 英語の用語や専門用語を確認してください。単語が辞書に存在する場合は、言語の正書法の規則に従って記述してください。
• その言語にその単語が存在しない場合は、元の言語で書き、括弧内にあなたの言語への翻訳を記入してください。
• その単語を用語集セクションに追加し、略語を略語と頭字語のリストに追加します。これは、「独自の」略語の場合に特に重要です (PO についてどれだけ言及されたり書かれたりしても、ドキュメントを読むときにその意味は依然としてよくある質問の 1 つです)。
• 一貫性 – ドキュメント全体で、選択した書き方と略語を守ります (社内で利用可能なすべてのドキュメントにとってより良い)。
• ドキュメントのナビゲーションを慎重に計画してください。文書全体を読まなくても、関連するセクションをすばやく見つける方法が必要です。したがって、明確かつ簡潔な見出しを使用してコンテンツを慎重に構成することが重要です。内部文書テンプレートは、シンプルさと利便性を考慮して開発する必要があります。

問題 4. ドキュメントを複数の場所で同時に作成する

文書化の場合、信頼できる単一の情報源、つまり正確さを気にせずに必要な情報を見つけることができる 1 つのスペースを確保することが重要です。当社の技術文書に関しては、社内で開発されたプラットフォームがそのようなスペースとして機能します。古い情報で誤解を招くことを防ぐためには、さまざまな場所でのドキュメントの断片化を避けることが不可欠です。

修理：

• 会社が知識共有のために複数のスペースを使用している場合は、技術ドキュメントをどこかに公開する前に、そのドキュメントが他の場所に存在しないことを確認してください。
• 古い技術文書をアーカイブまたは削除します (所有権がある場合)。時期尚早な削除 (たとえば、ページへの外部リンクによる) が心配な場合は、ページが古いことを示す吹き出しと、さらに更新する必要がある有効なドキュメントの現在のドキュメントの場所を追加します。
• 貴重な情報や洞察を見つけた場合は、ドキュメントに追加してください。 Slack やその他の場所、特にプライベート チャットに残さないでください。共有する価値のある知識!

投稿者:アンナ・ゴンチャロワ