对于初学者文档应该怎么编写呢？使用什么模板或格式？

Posted 2020-07-01 三小

在一个项目从开始提出需求到实施结束，这个过程会涉及很多文档的编写，在编写的过程中，对于初学者来说并不好把握，常常会不知道使用什么格式、排版，内容要怎么来写。

　　一般来说通用的模板内容大都内容全面、详细，比较复杂，初学者没有经验写起来会比较吃力。所以编写时可以使用通用模板进行模仿，但不用全部照搬。

　　实际上编写文档就像写作文，只要条理清晰的讲述出相关内容，突出重点，不要偏离该文档主题就可以了。当然如果你能详细的将5个W2H原则说明清楚，再配上相应的图例（流程图），那就更棒了。

　　5个W2H原则说明：1.WHY ——为什么？为什么要这么做？理由何在？原因是什么？2. WHAT——是什么？目的是什么？做什么工作？3. WHERE——何处？在哪里做？从哪里入手？4.WHEN——何时？什么时间完成？什么时机最适宜？5. WHO——谁？由谁来承担？谁来完成？谁负责？6.HOW——怎么做？如何提高效率？如何实施？方法怎样？7. HOW MUCH——多少？做到什么程度？需要多少时间？数量如何？质量水平如何？费用产出如何？

不同文档的主题是什么？

　　需求文档主要是为了让实施方了解软件开发完成后要达到的效果，以及和需求方对软件功能进行文档确认。

　　概要设计（总体设计）文档主要是为了和需求方进一步确认需求，以及软件设计的功能是否设置合理。同时也作为后面详细功能设计、数据库设计以及其他相关设计的总体指导，了解开发过程中需要使用的基本算法，以及可能遇到的问题。也方便将详细设计以及相关设计任务进行切分，分配给不同的负责人共同编写，减少花费时间。

　　详细设计文档主要是将总体设计里所讲述的内容进行细化，详细描述所要实现的功能、算法以及流程图。细化到每个页面要放置什么按钮、字段，列表中要显示什么内容，页面要实现什么功能，而实现这些功能可能要使用什么算法等。当写完详细设计后整个项目基本上就出来了。

　 　数据库设计是一个很重要的环节，因为好的设计会给整个系统带好良好的性能，为开发过程中减少不必要的代码，提高开发效率有着很重要的帮助。数据库设计是 根据详细设计里所描述的内容转换成开发中的数据表与字段。而在进行数据库设计时，常常会发现很多之前没有考虑到的问题，会有很多新的想法与需求，需要添加新的字段，这时在添加的时候必须进行反复斟酌，判断是否是必须添加的，是否必须在第一期开发中实现？能否放在第二期开发？对开发时间有没有影响？影响有多大？因为很多新的想法与扩展都不是必须的，很多想法也需求实现后都没有真正使用到，这样的话就浪费时间。我们必须要按计划与需求来进行开发，而不是随意的添加新的功能进来，这样才能做好开发进度的把控工作。而添加后必须同步更新详细设计文档，补充新添加的字段或功能描述。
　　
　　项目开发计划（甘特图）文档，主要是将详细设计里的每个功能，在实施时进行开发人员，以及开发先后顺序安排，并确认所需时间，制定开发计划。

 

 

 

　　单元测试文档，主要是编写各种测试用例，包括各种极限用例的提交以及返回结果的预期文档，帮助测试人员以及开发人员完善功能设计。

 

 

 

　　部署文档主要是将发布到生产环境的操作步骤以及注意事项进行详细描述，方便相关管理人员能轻松的部署最终上线版本，出现问题时快速找出并解决问题。