写前端文档

开发 前端
我想前端开发过程中, 无论是团队开发, 还是单兵做站, 有一份开发文档做规范, 对开发工作都是很有益的. 本文为你介绍了写前端文档的注意事项,以及前端文档缺失的原因。

我想前端开发过程中, 无论是团队开发, 还是单兵做站, 有一份开发文档做规范, 对开发工作都是很有益的.

前端文档缺失的原因

前端开发的文档相信大多数情况下都没有后端的服务描述详细,而大多数测试也仅仅在黑盒测试,所以很多情况下对这片文档的描述都廖廖无几。

1、前端开发的代码分散——没有规范化,没有很好的设计,大多数人仍以业务为主的开发方式。

2、测试人员对前端仍然处于黑盒测试,有没有文档都不影响到他们的测试进程。

3、一旦业务定型,用传统方式的文档模式,很难复制到前端开发来。——改变了开发方式(从作坊式到规范化)让人难以适应。

尝试对症下药

对于代码分散的问题需要从源头解决。从规范化开始,试点从头到尾惯穿规范化,强制的约定,使代码质量提高。
这一块需要下大力气,中间加入设计review、代码review等环节。需要注意的是粒度把控,即什么是必须的,什么是可选的,什么是约定的等有共识。

1、功能描述

开发前的工作,对编码者来说必须收集需求。对于使用者来说,能够知道写这个代码的目的是什么,解决了什么问题,还有什么问题没有解决,或需要改进。

2、设计描述

分享你的思想,这很重要,一个成熟的开发人员看开码的时候很多时候不是看你实现如何如何,而是看你的设计。

3、API描述

使用者快速上手。接口是代码的眼睛。命名要严谨,不能说也可这样,也可那样。经验告诉我们,接口做得不好,历史原因就会多。

4、demo/snippets

给使用的人copy/paste没什么不好。

5、使用指南

例如库的使用指南等手册。或者说一个简单的上手教程

文档该由谁来写?

从理论上看,文档都应该由编码者来写,其实不然。一个软件的周期,可以分为:开发前,开发时,使用时,测试时,维护时。
那么各时间段上应该有不同的人来参与。缩小些范围来看的话,应该将:

1、开发前收集需求由大家参与。实现者收集后存档到文档里。此为开发目的与预期。

2、开发时的API描述,设计描述主要由编码者来实现。

3、开发后/维护时的demo及snippets可以由使用者来完善。

设计文档是否能自动化生成

代码注释(现在一般都用java doc)可以生成接口文档。

以往都必须自己画设计图,配上描述。那么理论上这块也应该可以通过注释加入设计的描述,通过文档生成的工具自动生成设计图。这样应该方便多了。

原文链接:http://www.never-online.net/blog/article.asp?id=294

【编辑推荐】

  1. 如何做好一份前端工程师的简历?
  2. 10项技能让前端开发者价值百万!
  3. 老Web前端设计者谈对div绝对定位的心得
  4. Web开发有多难?前端后端都很烦
  5. 网站加速 美工和前端开发人员也很关键
责任编辑:于铁 来源: rank's technical notes
相关推荐

2020-04-03 10:57:09

文档分支项目

2017-01-16 13:26:39

2017写前端

2011-11-01 10:12:09

Web

2021-09-08 08:34:37

Go 文档Goland

2019-11-29 20:31:08

SphinxPython编程语言

2013-01-22 13:50:11

程序员前端Web

2021-10-12 19:16:26

Jest单元测试

2015-11-19 16:22:58

产品经理需求文档

2021-03-04 15:43:29

前端测试工具开发

2023-02-03 16:03:17

TypescriptJavaScript

2017-10-14 22:45:55

前端

2021-08-16 08:02:34

技术文档代码

2023-01-06 09:07:21

前端技术方案

2018-01-24 10:48:34

神经网络深度学习前端

2022-03-10 10:12:04

自动化脚本Bash

2013-11-07 09:14:32

程序员项目经理

2020-09-11 10:24:04

设计移动端交互输出文档

2020-08-28 13:20:53

谷歌Android开发者

2012-09-19 10:37:37

jQueryJSWeb

2013-09-05 11:05:29

点赞
收藏

51CTO技术栈公众号