開発者のライティング - 文章でも認められる開発者になるための必読書！

人工知能が開発を手伝う昨今、コードをうまく組むだけでは不十分な時代です。ドキュメンテーション、技術ブログ、ユーザーフレンドリーなメッセージの作成など。 ライティング能力は今や有能な開発者の必須条件です。

개발자의 글기
( 出典： 開発者のライティングカバー )

キム・チョルソンさんの『開発者のライティング』は、このような変化に合わせて、開発者がライティングでより多くの価値を創出するための実用的なガイドです。 この記事では、各章の主な内容を要約し、なぜこの本が開発者にとって必読書であるかを説明します。

「開発者のライティング』書籍概要

  • 著者：金鐵洙洙
  • 出版社: ビージェイパブリック
  • 出版年：2019年
  • 対象読者開発者、企画者、IT従事者など、ライティング能力を必要とするすべての実務者
  • 特徴:
    • コード内ライティング(変数名、コメント)からコード外ライティング(技術ブログ、提案書など)まで網羅。
    • 実務中心の事例と実践的なガイドを提供。
    • 開発者の視点からアプローチした明確で実用的なライティング方法論。

コアメッセージ

1. ライティングの重要性

- 開発者のライティングは、コードを超えてコラボレーション、コミュニケーション、問題解決能力を強化する必須スキルです。

2. コードとドキュメントのバランス

- よく練られたコードと同じくらい重要なのが明確なドキュメントです。文書化はプロジェクトの生産性と保守性を高めます。

3. 明確で簡潔な文章

- 読者を考慮した書き方は、技術的な内容の伝達をより効果的にします。

4. 即座に実務に適用可能

- この本の原則と方法論は、実務ですぐに活用できるよう、具体的で実用的な内容を扱っています。

第1章: 開発者が知っておくべきライティングの基本

開発者のライティングの最初の章では、ライティングの基本的な哲学と構造を扱います。

1.正確性、簡潔性、読みやすさ

  • 正確な情報を伝えつつ、不要な内容を減らし、読みやすい構造を作ることが重要です。
  • 読者の視点を考慮して優先順位を決め、文章のコアメッセージを簡潔に伝えましょう。

2.文の構造化

  • 要点を先に提示し、詳細な説明を付け加える ピラミッド構造をお勧めします。
  • 重要な内容を一番前に配置することで、忙しい読者も主要な情報を把握しやすくなります。

3.フォーマット選択

  • 記述式、改造式、回路図など シチュエーションに合ったライティング形式を選択してください。
  • 例えば、リリースノートは改変式が適しており、技術ブログは記述式が効果的です。
( 開発者の文章抜粋 - 出典：教保文庫 )

第2章: 開発時間を短縮するネーミングとアノテーションの書き方

良いネーミングとコメントの作成は、チームメンバー間のコミュニケーションを円滑にし、メンテナンスを容易にします。

1.命名規則

  • 変数と関数の名前は直感的で、チーム内で一貫性を保つ必要があります。
  • 例：totalVisitorsはvisitorCountよりも検索と理解が容易です。

2.注釈の書き方

  • 必要な場合のみ作成: よく書かれたコード自体がコメントの役割をする必要があります。
  • コンテキスト説明: なぜこのコードが必要なのか、どのような意図で書かれたのかを書きます。

例

  • 悪い例：// カウントに1つ追加します。
  • 良い例：// ユーザー数を1増やし、在庫調整を反映します。

第3章：ユーザーとコミュニケーションするためのエラーメッセージの書き方

ユーザーフレンドリーなエラーメッセージは、問題解決だけでなく、ユーザーエクスペリエンスを大幅に向上させます。

1.エラーメッセージ作成の原則

  • 内容：エラーの原因と問題を明確に説明。
  • 解決方法: ユーザーが真似できる解決策を提示。

2.悪い例と良い例

  • 悪い例：Invalid input.
  • 良い例です：入力された値が無効です。 名前はハングルのみ入力してください。

3.ボタンメッセージの上下動

  • 悪いボタン: はい/いいえ
  • 良いボタン: 保存後に出る / 保存せずに出る

第4章: リーダー視点でリリースドキュメントと障害レポートを書く

リリース文書と障害報告書は、ユーザーと会社間の信頼を形成する重要な文書です。

1.変更ログの書き方

  • 項目をユーザー視点で分類：新機能、改善点、エラー修正に分けるか、ユーザーフロー（開始-中間-終了）に沿ってまとめます。
  • 不必要なディテールを取り除き、簡潔かつ明確に表現しましょう。

2.まとめとまとめ

  • 改変式で要約し、読みやすさを向上させ、核となるメッセージを強調します。
  • はい：ゲームセンターへの入場が早くなります。

3.問題解決中心のレポート

  • 問題、原因、解決策、フォローアップ計画の順に書きます。
  • 読者が現在の状態を簡単に理解できるようにします。
개발자의 글쓰기 - 풍부한 사례와 예시 그림
( 開発者の文章抜粋 - 出典：教保文庫 )

第5章: 説明、描写、論証、物語で開発ガイドを書く

開発ガイドは、読者が理解しやすいように説明と論証をうまく活用する必要があります。

1.説明

  • サービスのカテゴリー、用途、特徴を明確に記述します。
  • はい：AWSのカテゴリー: "クラウドストレージサービス"

2.記述

  • 複雑な構造は、絵と文章を併用して説明します。
  • 文と絵の一致：視覚資料とテキストの内容が一致している必要があり、混乱を防ぐことができます。

3.論証

  • 主張に具体的な根拠を付けて読者を説得しましょう。
  • 例： "30まで値を上げても性能差がないことをテストで確認。"

第6章：受注に役立つSI提案書の書き方

SI提案書は会社の競争力を示す重要な文書です。

1.構造化された提案書の作成

  • 問題定義：顧客のニーズと問題を明確に把握する。
  • 解決策：当社のソリューションが提供する価値と具体的な実行計画。

2.強みアピール

  • 競合他社との差別化された強みを強調します。
  • 例:「私達のサービスは20%より速い処理速度を保証します」。

第7章：技術ブログを簡単に書いて運営する

技術ブログは、個人のブランド構築やコミュニティへの貢献に非常に便利なツールです。

1.書き方のコツ

  • 自分の視点で、経験とデータをもとに書きましょう。
  • 読者のレベルを考慮しつつ、自分のオリジナリティを保ちましょう。

2.操作のヒント

  • 定期的に投稿して信頼を築きましょう。
  • 簡単なコードスニペットや実験結果を含めるとより効果的です。

開発者のライティングレビューまとめ

「開発者のライティング』は、開発者が必ず知っておくべき実用的なライティングガイドを提供します。コーディングだけが得意な開発者ではなく、ライティングで価値を加える開発者に成長したいなら、この本をぜひ読んでみてください。あなたの開発もライティングも一段階アップグレードされることでしょう！

#開発者のライティングブック登場用語説明

1.リリースノート (Release Note)

  • 定義: リリースノートは、ソフトウェアの新しいバージョンがリリースされたときに追加された機能、修正されたエラー、改善点などを記録した文書です。
  • 目的: ユーザーと利害関係者にソフトウェアの変更を知らせるために使用されます。
  • コンポーネント：
    • 新機能：ソフトウェアに新しく追加された主な機能。
    • 修正されたエラー：以前のバージョンで発生したバグや問題が解決された内容。
    • 改善点：パフォーマンス、UI/UX、安定性などソフトウェアが改善された部分。
  • 例：
    • [バージョン1.2.3］
    • 新機能：ダークモードが追加されました。
    • 改善点：ページ読み込み速度20%向上。
    • エラーを修正：ログイン失敗時のエラーメッセージが正確に表示されるように修正。

2.変更ログ (Change Log)

  • 定義：変更ログは、ソフトウェアの変更履歴を記録した文書です。リリースノートのベースとなる内部記録として見ることができます。
  • 違い（リリースノートと比較）：リリースノートは外部ユーザーを対象としており、変更ログは開発者や内部チーム向けに作成されます。
  • 変更ログは、より詳細で技術的な内容を含んでいます。
  • 活用：開発者間のコミュニケーションを円滑にし、修正履歴を追跡する際に使用されます。

3.SI提案書

  • 定義：SI(System Integration)提案書は、システム統合プロジェクトを受注するために作成される文書です。
  • 目的: 顧客の問題を分析し、それを解決するための技術的/運用的なソリューションを提示します。
    • コンポーネント：
    • プロジェクト概要：お客様のご要望と目標。
    • 技術的なソリューション: 提案する技術とシステム構造。
    • 期待効果：プロジェクト完了後に期待される成果。
  • 重要性：提案書の完成度によってプロジェクト受注の可否が決まるため、非常に重要です。

4.ネーミングコンベンション (Naming Convention)

  • 定義：コード内で変数、関数、クラスなどの名前を体系的に付けるルールです。
  • 主なコンベンション：
    • キャメル表記（Camel Case）：最初の単語は小文字で始まり、その後の単語の最初の文字を大文字で表記。
      • 例: totalVisitors, calculateSum.
    • パスカル表記 (Pascal Case)：すべての単語の最初の文字を大文字で表記。
      • 例：CalculateSum、TotalVisitorsCalculateSum、TotalVisitors。
    • スネーク表記（Snake Case）：すべての単語を小文字で書き、単語の間にアンダーバー_を使用。
      • 例: total_visitors, calculate_sum.

5.コメント (Comment)

  • 定義: コメントとは、コード内で特定のコードの目的や動作を説明するテキストです。
  • 種類：
    • ラインコメント: 一行コメント。通常 // または # で始まる。
      • // ユーザー入力値を初期化します。
      • input = ""；
    • ブロックコメント: 複数行のコメント。/* */ または """"""で記述。
      • /*
      • この関数はユーザーデータを保存する役割をします。
      • 保存形式: JSON
      • */
  • 役割：コードの理解度を高め、メンテナンスを容易にします。

6.技術ブログ

  • 定義：開発者が自分の経験、技術、ノウハウを共有するために作成するブログです。
  • 目的：
    • パーソナルブランディング：自分を技術的に知らせ、ネットワークを広げる。
    • コミュニティへの貢献：有用な情報を共有し、開発者コミュニティに貢献します。
  • 書き方のコツ：経験とデータを中心に具体的に書く。コードスニペットやビジュアルを含めて読みやすさを高める。

7.ユーザーフレンドリーなエラーメッセージ

  • 定義：ユーザーが問題を理解し、解決するのに役立つメッセージです。
  • 要素:
    • エラー内容: 何が問題なのかを明確に説明。
    • 原因: エラーが発生した理由。
    • 解決方法：ユーザーがエラーを解決するための具体的な指示。
  • 悪い例と良い例：
    • 悪い例：エラー 404
    • 良い例です：ページが見つかりません、URLを再確認してください。

開発者の文章とともに、開発者向けの推薦図書があります。 開発者のおすすめ本 - 「ソフトスキル」、開発と生活の完璧な調和のための必読書！ ポストを通してその内容を確認してみてください！開発者のライティングブックと一緒に、開発者の世界に一歩深く入り込むことができます。

類似の投稿