软件文档编写

创建时间：2021/9/7 16:15

道理
- 软件文档的种类
- User Guide/Manual/Handbook
  - Importance
  - 最好包含的元素
  - 不同风格的User Guide
    - 较正式的文档
    - 较直接的文档
    - 按照角色划分的文档
  - 一些经验
- 相关资料

道理

软件文档的种类

https://en.wikipedia.org/wiki/Software_documentation https://blog.prototypr.io/software-documentation-types-and-best-practices-1726ca595c7f

需求文档 vs. 用户手册软件产品用户手册又叫软件产品使用说明书，面向用户，提供产品的安装操作使用说明。文档目的：产品完成后提供给用户一个安装、操作使用说明，提高售后人员的响应，帮助户更好的操作使用产品。（软件开发完成）

软件需求文档面向公司内部销售、研发、设计等人员，提供给销售理解产品，提供给研发作为开发依据，提供给设计作为设计框架。文档目的：需求文档主要介绍产品主要内容与功能。通过对每个功能进行详细的描述，可以让阅读者快速全面地了解该系统的功能。方便客户和需求分析人员之间的沟通，让设计人员、测试人员、开发人员更好的了解用户的需求。（软件开发迭代中）

User Guide/Manual/Handbook

A user guide is intended to assist users in using a particular product, service or application. It's usually written by a technician, product developer, or a company's customer service staff.

Importance

User documentation is important because it provides a avenue for users to learn:

how to use your software
features of your software
tips and tricks of your software
how to resolve common problems with your software

I once heard a rumor about Steve Jobs. According to this rumor, he said "if you need to write a manual for your software, you have done something wrong". I think the point of this rumor is to design your software to be as clear as easy as possible to use. However, good user documentation can make or break the success of your product. The design, presentation, and evaluation of your user documentation is really important part of developing software. Sadly, it is also an area much-neglected, as software developers might think it is boring.

Ref: https://computersciencewiki.org/index.php/User_documentation