テクニカルライティングガイドライン

Technical Writing Guidelines

はじめに

テックリードやアーキテクトにとって、どれだけ優れた設計案を描けても、関係者に伝わり実行されなければ価値を生まない。そのため、純粋なIT技術力と並んで「説明力」が重要である。

報告や提案などの実務において、第一報の多くはドキュメントやチャットを通じた文章（ライティング）である。構造化された簡潔な文章は、受け手の時間を奪わず正確な情報を伝達し、非同期での合意形成を促進する。

本ガイドラインが扱うのは、情緒的な散文や単なる文章の作法ではない。専門概念を構造化し、判断に足る情報を示し意思決定を推進するための技術である。

本ガイドラインで扱う文書の前提
次のように多岐を想定している。その文章のコンテキストごとに求められる期待や文量が異なるが、なるべく一般的に適用できる事項から紹介している。

日常的なコミュニケーション: チャットメッセージ、コミットメッセージ

プロジェクトの推進・合意形成: 提案書、報告書、設計書

不特定多数への技術発信: 技術ブログ、雑誌の記事、書籍

参考

ソフトスキルガイドラインでも、4つ目のスキル分類を「説明力」とした。

免責事項

有志で作成したドキュメントである。フューチャーには多様なプロジェクトが存在し、それぞれの状況に合わせて工夫された開発プロセスや高度な開発支援環境が存在する。本ガイドラインはフューチャーの全ての部署／プロジェクトで適用されているわけではなく、有志が観点を持ち寄って新たに整理したものである
相容れない部分があればその領域を書き換えて利用することを想定している。プロジェクト固有の背景や要件への配慮は、ガイドライン利用者が最終的に判断すること。本ガイドラインに必ず従うことは求めておらず、設計案の提示と、それらの評価観点を利用者に提供することを主目的としている
掲載内容および利用に際して発生した問題、それに伴う損害については、フューチャー株式会社は一切の責務を負わないものとする。掲載している情報は予告なく変更する場合がある

本書の構造

本ガイドラインは、ソフトウェア開発のライフサイクルになぞらえた構造となっている。実際の目次はフラットな章立てだが、概念的には以下の5つのフェーズを辿るように構成されている。

設計

執筆（実装）

実践応用

品質向上

育成

謝辞

このアーキテクチャガイドラインの作成には多くの方々にご協力いただいた。心より感謝申し上げる。

作成者: 真野隼記、Tiffany Chan、高瀬陸、内堀航輝、宮崎将太、小橋昌明、亀井隆徳、戸井田拓斗、武田大輝、清水雄一郎、赤坂優太、澁川喜規、長谷川寛人

レビュアー: 辻大志郎

はじめに ​