---
title: "软件文档编写"
author: "Perrin Yong"
author_profile: https://www.pystone.net/profile/
published_by: "Perrin Yong"
canonical: https://www.pystone.net/notes/software-documentation-writing/
type: note
content_role: unspecified
visibility: public
id_stability: rename-stable
source_path: "10-计算机、信息技术与工程/03-软件工程与质量保障/软件工程与项目管理/软件文档编写.md"
content_hash: 1ec5dcde425b10abea323890dc18784b9738bd0ef1748369c152756c3d5f1e3b
knowledge_version: 224c990773de.5fa8af6e39fa
site_commit: 224c990773de166d23a886306577dd90379529ce
notes_commit: 5fa8af6e39fa3891d1b9b4832bfa6c4e0ecaaf0a
---
# 软件文档编写
> 创建时间：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:

  1. how to use your software
  2. features of your software
  3. tips and tricks of your software
  4. 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

* * *

### 最好包含的元素

  * FAQs
  * Video tutorials
  * Embedded assistance (for example, tool tips and dynamic page content)
  * Support Portals

### 不同风格的User Guide

#### 较正式的文档

https://wiki.mbalib.com/wiki/用户手册

![assets/0001 - 软件文档编写__resource-003-e6b9e7a1e61c.png](/media/c940b9fcdeeae977d5bb.png)

![assets/0001 - 软件文档编写__resource-004-d28daec0142c.png](/media/116c1ffef7d19ea186b3.png)

#### 较直接的文档

https://support.google.com/earth/?page=guide_toc.cs#topic=7364880

![assets/0001 - 软件文档编写__Image.png](/media/7ecaaaf9b66fe3b5dc67.png)

#### 按照角色划分的文档

http://docs.autodesk.com/TOPOBSCLNT/2010/ENU/Autodesk%20Topobase%202010%20User%20Documentation/index.html?url=WSfacf1429558a55de9af080101d7e8b304-7c61.htm,topicNumber=d0e342

![assets/0001 - 软件文档编写__resource-002-cc49b4d63043.png](/media/9729a449fcbdc4aad7fb.png)

### 一些经验

https://www.userfocus.co.uk/articles/usermanuals.html
https://blog.screensteps.com/10-examples-of-great-end-user-documentation

## 相关资料

Great End User Documentation: https://blog.screensteps.com/10-examples-of-great-end-user-documentation

软件产品开发过程文档：https://bibichuan.github.io/posts/ce5650a0.html

https://zhuanlan.zhihu.com/p/29497473