文書の広い範囲が、この記事では、具体的に参照する背景には、基本的な製品と主要な技術的な設計文書が含ま作成する開発者。
世界観
なぜ書き込み技術文書
さらに言えば、私は個人的に完了するために、チームを助けることができる技術文書を作成し、その答えに非常に簡単にそれを見つける
現在の情報共有や長期的な知識伝達を。個人の場合は、一方ではそれができ
、時間を節約、
過去の知識を取得することも簡単な答えは、重複を避けるためにあるため、しかし、できる一方で口の中の単語を作成し
、そのような特定のように突然同僚は、私が文書を書いたことを私にメッセージを与えました大きな助けのこのビジネスに新しい人々のために良いです。
特定の同僚に感謝します。
音声の文書化の必要性に反論
プログラマの多くは、ビューのポイントを所持してあります：「（書き込み）のドキュメントを見てはいけない、文書は、コード内にある、」まだいくつかの人々は文書が簡単に日付に、更新されたコードのリズムに追いつくことは困難であると信じてありますので、文書を記述する必要はありません。
状況につながったすべてのこれらの見解はこれです：
彼らはこのようなものを説明する必要を感じていないとき人々は、事業譲渡をビジネスTucao書き込みドキュメントを引き継ぐしていない場合は、ドキュメントを必要としません
。
この点で、最初にすべての私は、コードの詳細を一部のお得な情報が文書を書くことが、全体的なデザインを変更し、ビジネス文書を書くために絶対に必要である必要はありませんだと思います。一部の人々は、彼らが、バージョン（変更履歴）の概念を導入していないので、それは、された文書の陳腐化があることを感じて
時代遅れの文書は、ビジネスの歴史の一部そのものである
、私はビジネスを引き継いだ、私たちはしばしば理解を助けるためにこれらの履歴情報を必要とします。
出向：文書でなぜ一見
上周发生了一件趣事，一个产品跟我说，
开发两句话能说明白的，为什么要看文档
？确实，问开发能以最快速度准确地获取信息，毕竟人脑就是一个强大的搜索引擎。但是长期来看有以下问题：
浪费开发时间
开发无法随时答复，浪费自己时间
信息无法固化、传承，而且过于琐碎，浪费团队时间
一般来说，一份 好的技术文档
比起开发口述是不会有多余的理解成本的，甚至更低，因为对于很多信息，图片能比语言更好地表达。
什么算好的技术文档
我认为 好的技术文档 的核心是 敏捷 。一方面，好的的技术文档是
高度可维护的并且经常维护
的，比如新增了一些功能，文档的作者能够快速更新文档，文档的读者能及时获取更新；另一方面，好的技术文档是
易理解 的，更详细来说要表述准确、结构清晰、排版美观、风格统一。
文档&写文档的定义
最后，我想探讨下写文档到底是干吗？百度百科说：
软件文档或者源代码文档是指与软件系统及其软件工程过程有关联的文本实体。
那么写文档就是生产这个实体的过程了。但这样实在过于抽象，根据我最近一年的经验来看，我更愿意将其定义为
对特定信息进行结构化整理的过程 。
以上就是写作技术文档的道了，也就是我们对于这件事最基础的世界观，接下来谈术，即基于此执行的方法论。
方法论
基调
在正式开始写文档之前，我们必须要有以下三点认知：
足够了解 ：
我们要为某个模块写文档，前提一定是我们对这个模块足够了解，只有基于此，我们的文档才是有价值的，否则只是信息垃圾。换位思考 ：
即便有了交接文档，我们也经常需要去询问交接人，这种情况屡见不鲜，究其本质，是因为很多时候我们都是站在自己的角度、按照自己的理解来写文档的，但是读者的信息背景和我们是完全不一样的，我们觉得理所当然的可能他们一无所知，所以写作文档必须要有足够的换位思考的意识。
文档是写给别人看的，不是写给自己看的 。MECE原则 ： 简单来说就是 相互独立，完全穷尽
，这个思想可以指导我们对文档结构进行组织。下面给出一个参考。
结构
本章节讨论了一份技术文档应该具备的各个单元，可以作为今后技术文档写作的框架或者Checklist。
Introduction
简单介绍项目背景信息，如下面是我为某个项目写的 Introduction ：
Content
目录，目录是结构的直接体现，必须有，一般文档写作工具都能自动生成：
Terms
术语解释，很多业务会衍生一些特定词汇，如“白条卡”、“大图卡”等，都是有特定语境的，需要单独解释。
Setup
如何运行这个项目，一般开源项目都会有，如果是SDK文档也常常有接入文档，就是这个模块。
Body
这部分就是文档的主体部分，具体结构需要视内容而定，有以下通用规则
一图胜千言，如Android的架构图、Actvity的生命周期图，比任何语言都好使。
Demo胜千言。
对于具体的格式规范，推荐阅读 ruanyf/document-style-guide:
中文技术文档的写作规范。
Reference
相关需求单：比如某个业务所有相关的需求单都放在这里，方便其他人更进一步了解背景，也方便自己查找。
参考资料。
这部分也可以放在附录里面，见下图。
FAQ
其他人经常问的问题，遇到就记录在这个模块，不断补充，日趋完善。
Appendix
一些比较冗长的信息可以放在附录里面，比如日志，避免放在正文影响排版和阅读。
ChangeLog
变更日志，一般开源项目都会记录每个版本的重要变更。
ReleaseNote
发版日志，一般开源项目都会有一个单独的Release页面。
过程
一般来说，文档写作的流程如下：
收集信息、整理框架、实践结论、写作文档
。如果前期工作足够，写作所花的时间是很少的。
此外，文档完成后，还要注意读者反馈，以不断完善自己的文档。
写一份好的技术文档也不是一蹴而就的，需要不断打磨，要注意经常去
刻意练习 。
工具
写作工具
一般来说，只要别人发给我的文档是一份Word文档，我基本就把这份文档排在了最LowB的一档。对于这种文档，我就想问两点：
文档有更新怎么分发给每个需要这份文档的人？
Word格式不兼容导致关键图表排版混乱怎么办？
一般来说，文档写作工具有以下选择：
Word
Pdf
Markdown
Asciidoc
Latex
WordのPDF /私は強く、多くの文書が更新されるので、両方のフォーマットを行うことができない、拒否
動的更新を。Markdownを
比較的人気のあるオープンソースコミュニティ、それは表現力とシンプルさのバランスを見つけましたが、それは致命的な問題があるため
、もう少し複雑なレイアウトに対応できないし
。Asciidocが私のメインのドキュメント作成ツールで、多くの人々はGithubのも、それがこのフォーマットである紙のようなこの文書フォーマットをサポート知りません。Asciidoc構文は値下げよりも複雑ですが、私が思うに
費用が学習する時間も価値があります
。最後に、ラテックス、テックス変異体は、最も強力なの表現、（特に複雑な数式を発現するもの）学術界で一般的に、より人気の、複雑なレイアウトを扱うことができますが、私は少しやり過ぎを書く日常の文書に考えますA。
要約すると、私はAsciidocをお勧めします。
メンテナンスツール
文書を管理するために、私は、文書の管理などの管理コードのように、Gitリポジトリを使用することをお勧めします。
他の同僚は、常に最新のドキュメントを参照してください訪問した際に加えて、私は、あなた自身のドキュメントを格納するために、静的なウェブサイトを使用することをお勧めします。
また、同社は現在、必ずIWikiを推進している、必ずIWiki私は最大の利点だと思うのアクセス制御
機密文書のためには必要不可欠です。しかし、必ずIWiki変更履歴と比較して、プログラマーとして、私はGitので管理好ましく、さらに、独自のローカルコンフィギュレーションエディタを比較することはできません確かに必ずIWiki Webページの編集経験があります。もちろん、手術が絶対的に良いか悪いかではない、それはまた、彼らが収まるかどうかによって異なります。
概要
上記、技術文書の作成についての最近の考え方。交換補正を歓迎しました。