一步一步教你如何写开发文档

已剪辑自: https://icocos.github.io/2017/01/02/%E4%B8%80%E6%AD%A5%E4%B8%80%E6%AD%A5%E6%95%99%E4%BD%A0%E5%A6%82%E4%BD%95%E5%86%99%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/

你有没有遇到过，突然老板或者老大跟你说，你根据项目或者根据功能写一份开发文档，当时很开心的答应了，后来想想，既然懵了。

开发文档是什么鬼？写了这么多年代码都没写过什么开发文档，最多也就只是产品的需求文档，说明文档，代码的注释与规范文档，或者说过苹果的开发文档，因为之前刚好写过一次很简单的，最近公司又开始要写上面开发文档了，而且发现确实很多同学都不会，我在想，我是不是该做点什么……。

前言

App开发过程中的文档分为很多种，比如最常见的就是官方的开发文档，这种比较倾向代码和接口，但是你可能还见过或者听过其他文档。

比如，这里根据个人理解整理了几个。

1. 开发文档
2. 需求(原型)文档
3. 需求(说明)文档
4. 技术方案文档
5. Bug修复文档
6. 注释文档
7. 代码与UI规范文档
8. 性能优化文档

是不是有点晕了，哪有这么多鬼，其实按照之前的习惯，我都是一份开发文档就够了，基本上包含上面的东西，只是看你怎么细分。

开发文档概述

实际开发中如果真的遇到要写上面开发文档可以从下面几个角度写。

• 一. 开发环境及工具
• 二. 项目或功能（需求）描述（最好有流程图或者UML）- 需求文档
• 三. 编写目的（用户特征和水平）
• 四. 项目或功能背景
• 五. 模块与关系
• 六. 类或术语说明
• 七. 参考资料（网络或公司内部资料，UI，原型，说明文档）
• 八. 项目进度预估
• 九. 难点预估（条件与限制）
• 十. 功能与所计划采用的技术 - 技术方案文档
• 十一. 用户界面与交互
• 十二. 软件（代码）接口 - 注释文档
• 十三. 通信（网络）接口 - 接口文档
• 十四. 问题与修复说明 - Bug修复文档
• 十五. 性能分析与优化

当然也不是说这些全部要写，可以根据项目或者功能适当编写。

下面大概一个个的说明一些每一个步骤是什么意思，需要怎么写，这里主要以iOS开发中App开发文档为规范，并使用苹果最新的语言Swift作为唯一语言。

• 一. 开发环境及工具
  • Mac OX 10
    • iPhone或者iPad 5+ 2+ 必须真机
    • iOS 8+
    • Xcode 8+
    • 其他工具：Tower，cornerstone

主要指明开发在工具，开发平台，开发版本的支持。描述软件的运行环境，包括硬件平台、硬件要求、操作系统和版本，以及其他的软

件或与其共存的应用程序等。

• 二. 项目或功能（需求）描述（最好有流程图或者UML）- 需求文档
  • 顶层数据流图；
  • 用例UseCase图；
  • 系统流程图；
  • 层次方框图。

主要根据产品给出的需求结合原型进行描述，并适当给出相应的图。

• 三. 编写目的（用户特征和水平）
  • 描述最终用户应具有的受教育水平、工作经验及技术专长。

次软件或者功能编写的目的，对项目，对用户，对公司有什么好处。

• 四. 项目或功能背景
  • 标识待开发软件产品的名称、代码；
  • 列出本项目的任务提出者、项目负责人、系统分析员、系统设计员、程序设计员、程序员、资料员以及与本项目开展工作直接有关的人员和用户；
  • 说明该软件产品与其他有关软件产品的相互关系。

此项目或功能编写之前市面上的情况，公司和用户的情况

• 五. 模块与关系

项目或功能对应模块在位置，入口，和其他模块的关系

• 六. 类或术语说明

项目或功能对应类的说明，和开发中使用到的一些相关的术语的说明

• 七. 参考资料（网络或公司内部资料，UI，原型，说明文档）
  • 列举编写软件需求规格说明时所参考的资料，包括项目经核准的计划任务书、合同、引用的标准和规范、项目开发计划、需求规格说明、使用实例文档，以及相关产品的软件需求规格说明。
  • 在这里应该给出详细的信息，包括标题、作者、版本号、发表日期、出版单位或资料来源。

网络资料，尤其是苹果的，也可以群里或者博客，文章等。公司内部的UI，原型，说明，网络接口资料

• 八. 项目进度预估

预计从上面开始到指定的时间节点完成任务或者完成对应的部分

• 九. 难点预估（条件与限制）

其中考虑到或者可能会遇到什么技术或者实现难点

• 十. 功能与所计划采用的技术 - 技术方案文档
  • 将要采用的图形用户界面标准或产品系列的风格；
  • 屏幕布局；
  • 菜单布局；
  • 输入输出格式；
  • 错误信息显示格式；
  • 建议采用RAD开发工具， 比如Visio，构造用户界面。

根据项目或者功能需求，在代码层面所使用的技术或者实现方案，或者比如说ios中布局方式的使用。

• 十一. 用户界面与交互

根据用户界面和入口说明交互与使用步骤并

• 十二. 软件（代码）接口 - 注释文档

每一个方法和属性对应的注释，一般是私有的话使用private但是也要注释，公开的都会使用标准的注释说明，苹果有自带的快捷键（command+option+/），之前有个插件叫VVDocument

• 十三. 通信（网络）接口 - 接口文档

网络请求对应的说明包括对应的参数，字段和返回值，也可以是数据模型层对应的模型属性和方法的说明

• 十四. 问题与修复说明 - Bug修复文档

开发或者测试的过程中出现了什么比较重要的bug，不要什么bug都写上，然后说明解决的方案

• 十五. 性能分析与优化
  • 时间特性
    • 响应时间；
    • 更新处理时间；
    • 数据转换与传输时间；
    • 运行时间等。
  • 适应性
    • 在操作方式、运行环境、与其他软件的接口以及开发计划等发生变化时，软件的适应能力。

到此完成之后，根据实际需求和个人能力，个人理解分析项目或者功能那些地方需要进行优化一下，打算怎么去优化他。

后期会继续完善(根据项目或功能整理一套完整的开发文档)…….

注：这里是按照功能，并不是按照整个项目分，如果要写整个项目的开发文档也可以再根据功能细分。