※本記事は、ChatGPTによる意訳+翻訳を活用し、レイアウト調整したものです。
※感想は、オリジナルです。
原文
The best software engineers write instead of code - DEV Community
意訳+要約
最高のソフトウェア・エンジニアは、コードを書く代わりに文章を書く
このブログでは、優れたソフトウェアエンジニアがコードを書く代わりに何を書くべきかについて述べられています。重要なポイントは以下の通りです。
- ドキュメントはソフトウェアエンジニアリングの重要な側面であり、コードと同じくらい重要である。
- 優れたドキュメントは、チームメンバーがコードベースを理解し、効果的に協力するのに役立つ。
- 読みやすく、明確で、的確なコメントを書くことが重要である。
- コードのコメントだけでなく、コードの意図や背景に関するドキュメントも作成するべきである。
- テストケースや使用例のドキュメントも重要である。
- ドキュメントは、プロジェクトの成果物として価値があり、将来のメンテナンスや変更に役立つ。
要約すると、ソフトウェアエンジニアはコーディングだけでなく、質の高いドキュメントを作成することも重要であることが強調されています。
ChatGPTへのQA
Ｑ：良いドキュメントを書くコツは、なんですか？
良いドキュメントを書くためのコツは以下の通りです：
明確さと簡潔さを重視する: 読み手が理解しやすいように、文は簡潔で明確であるべきです。冗長な表現や曖昧な言葉は避けるべきです。
読みやすさを考慮する: 文章を読みやすくするために、適切なフォーマット、レイアウト、タイトル、見出しを使用し、段落を適切に区切ります。
ターゲットオーディエンスを意識する: ドキュメントを書く際に、誰がそのドキュメントを読むのかを考慮します。読み手の知識レベルやニーズに合わせて情報を提供することが重要です。
適切な技術レベルを維持する: ドキュメントの技術レベルは、読み手の理解能力に合わせて調整する必要があります。初心者向けの基本的な説明から、上級者向けの詳細な情報まで、適切なレベルで情報を提供します。
具体的な例を提供する: 読み手が理解しやすいように、具体的な例や使用方法を提供することで、説明を補強します。
正確性を保つ: ドキュメントに含まれる情報は正確で信頼性が高いことが重要です。間違った情報や誤解を招くような記述を避けるため、情報を確認し、必要に応じて最新の情報を反映させます。
フィードバックを受け入れる: ドキュメントを作成する際に、他のチームメンバーや読み手からのフィードバックを積極的に受け入れ、改善を加えることが重要です。
Ｑ：上記を実現するためのツールやソフトは何かありますか？
良いドキュメントを作成するために役立つツールやソフトウェアはいくつかあります。その中には以下のようなものがあります：
ワードプロセッサー: Microsoft WordやGoogle Docsなどのワードプロセッサーは、文書を作成し、編集するための基本的なツールです。簡潔で読みやすい文書を作成するために利用されます。
ドキュメント作成ツール: Markdown記法を使用するツールやドキュメント作成プラットフォーム（例：Markdown Editor、Typora、Notion）は、技術文書やプロジェクトのドキュメントを作成するのに役立ちます。Markdownは簡単な記法であり、見出しやリストなどの構造を簡単に作成できます。
バージョン管理システム: ドキュメントの履歴を追跡し、変更を管理するために、バージョン管理システム（例：Git、Subversion）が使用されます。複数の人が同時にドキュメントを編集する場合や、変更履歴を追跡したい場合に役立ちます。
図表作成ツール: ドキュメント内に図や表を挿入するために、グラフィックソフトウェアや図表作成ツール（例：Microsoft Visio、Lucidchart、draw.io）が使用されます。これらのツールを使用して、情報を視覚的に表現することができます。
静的サイトジェネレーター: 技術文書やドキュメントをウェブページとして公開する場合、静的サイトジェネレーター（例：Jekyll、Hugo、Gatsby）が役立ちます。これらのツールを使用すると、MarkdownやHTMLなどのファイルからウェブページを自動的に生成することができます。
これらのツールやソフトウェアを組み合わせて使用することで、効果的なドキュメント作成プロセスを構築することができます。
Ｑ：オーディエンスを意識するにしても、バックボーンや文化の違いが問題になると思うのですが、多様性は排除したほうがいいのでしょうか？
いいえ、多様性を排除することは良いドキュメント作成の観点からは望ましくありません。オーディエンスを意識する際には、異なるバックボーンや文化を考慮することが重要です。なぜならば、異なる文化やバックボーンを持つ人々が異なるニーズや理解力を持っているため、その多様性を尊重し、包括的なアプローチを取ることが必要です。
多様なオーディエンスに対応するためには、以下のような点に配慮する必要があります：
言語の選択: オーディエンスが異なる言語を話す場合、複数の言語でドキュメントを提供することが重要です。必要に応じて翻訳を提供し、多言語サポートを考慮します。
文化的な配慮: 文化的な背景や慣習に配慮し、誤解や誤解を避けるために、適切な表現や例を選択します。特定の文化に関連する例やメタファーを使用する際には、文化的な敏感さを持ちます。
アクセシビリティ: 異なる能力やニーズを持つ人々に対応するために、アクセシビリティの考慮が重要です。例えば、視覚障害者や聴覚障害者向けに、適切な形式や補助技術を提供します。
異なる技術レベルに対応する: オーディエンスの技術レベルが異なる場合、初心者向けの基本的な説明から、上級者向けの詳細な情報まで、適切な情報を提供します。
多様性を排除することなく、異なるバックボーンや文化を尊重し、包括的なアプローチを取ることで、より幅広いオーディエンスに有益なドキュメントを提供することができます。
Ｑ：表現の幅が狭まるデメリットがあると思われますが、その点についてはどう考えていますか？
確かに、異なる文化やバックボーンを考慮することが必要な場合、表現の幅が狭まる可能性があります。これは、特定の表現や例が特定の文化や背景に関連しているため、全体的な表現の幅が制限されることがあるからです。
ただし、この制限は必ずしもマイナス面だけではありません。異なる文化やバックボーンを考慮することで、より包括的で配慮深いドキュメントを作成することができます。このようなアプローチは、多様なオーディエンスに対してより有益で効果的なコミュニケーションを実現することができます。
また、表現の幅が狭まると感じる場合でも、創造的な解決策や代替案を見つけることができます。異なる文化や背景を尊重しながらも、より広い範囲のオーディエンスにアピールする方法を探求することが重要です。
総括すると、表現の幅が狭まるデメリットがある一方で、異なる文化やバックボーンを考慮することで得られる利点があります。バランスを取りながら、できる限り多くの人々に適切に伝えるための努力をすることが重要です。
感想＋雑記
文章を書くのがプログラミングでも応用可能であることは、よく言われる。
それだけではダメだとは思うけどな。
結局、ソフトウェア工学が重要になってくる。
ドキュメントは、チームで活動する場合に重要ってだけな気がする。
あと、多様性うんぬんは、個人的には懐疑的。
多様性大事みたいな雰囲気の今の社会は、かなり疑問を感じてる。
文化や背景が人に与える影響は、かなり大きいと思うんだよね。
それを無視して誰でも読めるドキュメントを作ったら、無味無臭な文章になる気がする。
そういう文章って、読むのがキツイんだよな。。。
