1. 聚能聊>
  2. 话题详情

云栖工具控 - 你是怎么写文档的?

写文档,也是一门艺术!

如何才能写一个便于维护,简明扼要的文档,可能是很多开发者都希望的!

analysis_1841158_640

有了好的文档,我们可以轻松的接手别人的开发。

也可以放心的将项目交给别人去做。

举个例子

我使用Makrdown和git来管理我的文档。Markdown可以让我更少的去关注格式的问题,git可以让我的文档有更多的把控,每次的改动都清晰可查,日后查询时,都可以很方便。
在我看来,一个好的文档,一定要能够高速用户是什么和怎么用。

诸位开发者,一起来分享你的写文档心得!

1. 你使用什么来写文档,为什么?

2. 你觉得一个好的文档,应该有什么必备的元素?

3. 你如何看待文档在你工作中的重要性

参与话题

奖品区域 活动规则 已 结束

  • 奖品一

    优酷VIP月卡 x 2

  • 奖品二

    星座淘公仔 x 2

  • 奖品三

    云栖大会订制T恤 x 1

129个回答

0

cofftea 已获得星座淘公仔 复制链接去分享

现在习惯自己搭一个wiki写文档,格式就是两种,一种自己看得懂,一种小白都看得懂,但是都要求仔细,全面,且二次修改方便。

西秦说云 回复

只有程序员懂wiki的好

评论
2

李博 bluemind 已获得优酷VIP月卡 复制链接去分享

在写文档前,你得思考,要写哪些内容, 我总结如下:

项目中关键处理逻辑

使用的框架
整个处理过程(譬如点击一个link或者button后,后续的完整处理流程和交互逻辑)
规范性内容(如编码规范,文档规范, 注释规范等等)

知识性内容(如某个工具的使用方法, 某个插件如何提高开发效率等)

经验性东西(如一些最佳实践, sql如何写, 如何保证代码的可复用性等)

教程性内容(如如何让一个新手使用当前的框架写出一个功能等,如何让他快速入门)

FAQ类似的内容(当你被同事或者客户同一个问题问了超过3遍时,你就应该写出文档来, 来避免再次被占用这宝贵的程序员时间)

当然上面提到的都是开发相关的文档, 也是我们每个程序员可能要写的. 还有几类文档, 如需求文档, 开发文档, 测试文档, 用户文档等, 也可能需要程序员参与.

除此而外,另一大类,就是代码的API, 这类文档最好的处理方式是自动化, 如 doxygen, epydoc 等一系列工具. 使用这样的工具, 可以免去重新写API的文档,只需要自动生成即可, 而后续如果代码和注释有更动,也只需要重新生成即可.

解决了写哪些内容, 我们来看,如何去与文档, 如何去维护文档.

这里有个参考: How to make documents evolve?

我经历过的团队, 有不写文档的, 有写文档但是经常会过时的, 也有维护较好的. 根据我个人的经验,我的建议是:

使用一个良好组织的wiki来作为文档管理系统, 对于项目中的文档中及时更新, 保证是准确和正确的.

当然,如果你不想去维护一个文档系统, 那么宁可不要文档, 因为 错误的文档还不如没有文档.

那么文档放在哪里合适呢?

个人建议是与代码一起纳入版本控制系统,如我在 你使用源码管理工具吗? 中推荐的 bitbucket, 中集成有wiki. 这样维护和更新起来都会比较方便.

结论
文档是一个公司实力的体现,也是管理者素质和能力的体现, 它对于开发者是极大的财富.所以维护一个良好组织的文档, 不仅能够在开发中让你获益无数, 而且在提高成员对团队的认可度,对公司的忠诚度等方面也会有很大的提升.

如果你们团队还没有文档,现在就开始写吧

1

gomaomao 已获得星座淘公仔 复制链接去分享

我使用showdoc来写文档。
因为开源,可定制,在阿里云服务器上搭建一个平台,公司内部不同的权限,随时随地都可以访问,提交!私有,合作都可以。
文档最重要的是看得懂!简短的话说清楚怎么用和注意事项就行。

1

averyboy 已获得优酷VIP月卡 复制链接去分享

markdown啊,文档博客都用它,用atom来写,自从接触markdown以来觉得这个东西真的好用,程序猿绝配啊,😂,觉得以前的office都白用了,写完文档格式也就好了,能让自己注重写的东西而不用在意格式啥的,全程不用动鼠标😄

1

猫咪在云栖 已获得云栖大会订制T恤 复制链接去分享

文档啊,是程序员学习程序最直接的一步吧。讲道理,有时候买很多书来读,真不如去读一下该技术官网所提供的文档:比如

android 所提供的官方文档,因特尔公司提供的FPGA的官方文档,这些对我们的学习程序员的学习有很多帮助的。为什么帮助很大,因为文档的起草要更为严谨,而且大部分文档是这个技术的发明者写的,也就是说当你阅读文档的时候,你是在和这个技术的发明者对话。可想而知,这是一件多么振奋人心的事情(=@__@=)呐!

这里写一个小小的教程,如果你想学习文档有关的知识啊 ,建议去看看md官网所提供的英文文档,然后学习使用git进行上传你的文档。
这也是我所使用的,使用MarkDown语言,ATOM作为编辑器,GIT作为版本控制的工具。这样就能高效的写出有用的文档啦~。

我是一个大三的学生,打算用几年的时间去规范自己的代码习惯,研究生学校想考去杭电。比较向往的公司是阿里巴巴,希望自己以后技术能达到阿里的要求吧。主攻硬件,软件只是爱好(但是也希望精通)。物联网工程专业,希望题主大大能送个衣服啥的(已了却我第一次穿科技公司文化衫的念想)。
以上就是俺的发言啦

1

1167147123186517 复制链接去分享

onenote!极力推荐!会用office,就会用这个!原来是office中的一员,现在作为独立项目。结合云盘onedriver,你懂的!

西秦说云 回复

嗯,可以尝试一下

评论
0

聚小编 复制链接去分享

一直在用聊主大人帮忙写的Makrdown,超级好用的说。其实更多的还是用文本编辑器...

西秦说云 回复

🍎

聚小编 回复

😓

happycc 回复

这个应该得奖。🉐️

评论
0

李文成 复制链接去分享

我觉得一个好的文档应该是有结构,结构清晰,言简意赅,但是谈到工具,除了好用的工具,还应该全平台都可以使用,同步,这样才是一个顺手的工具。我一直觉得,文字排版美观能够激发我的创造力,但是有的时候会过多纠结于使用哪个工具,反而浪费了很多时间,看到那些不用纠结工具,即使使用文本文档也能做的很好的人,确实很羡慕,以后不应该把时间浪费在工具的选择上,挑一个自己最常用的就好了。

西秦说云 回复

那你到底用的什么工具呢?

评论
1

1762106949652124 复制链接去分享

使用阿里云服务器搭建的在线文档管理系统 欢迎尝鲜 wiki.52qdw.cn
317d24284a104d558a83ea864d0e1dc9_94a2902419dc49eb840b43ec10fdf796.jpg

kill_it 回复

开源吗?

评论
0

1813821045935829 复制链接去分享

只有代码注释没有文档😂

慕容望月 回复

我注释都懒得写😜

woroot 回复

😂看自己代码都绝望一大筐都不知道怎么写下来的(css)

评论
2

happycc 复制链接去分享

  1. 你使用什么来写文档,为什么?
    公司办公,为了通用,多数都是office来完成,2013 -2016 ,都是免费的。 论文更是必须这个了。

如果是技术开发使用everdite . sublime

_2017_03_28_22_14_30

编辑器除了要有基本的代码的功能之外,
非常非常重要的就是 。 vi 功能一定要有,没有vi插件的编辑器,太影响效率。

  1. 你觉得一个好的文档,应该有什么必备的元素?

vi

  1. 你如何看待文档在你工作中的重要性

语言沟通之外的,

第二大核心元素,无可取代,不是吗。

2

似水的流年 复制链接去分享

用showdoc写合作的文档,showdoc用在it行业感觉还是蛮流行的,他也是基于markdown编辑器,无论是编辑还是阅读体验都极佳很棒。
ShowDoc就是一个非常适合IT团队的在线文档分享工具,它可以加快团队之间沟通的效率。
API文档
随着移动互联网的发展,BaaS(后端即服务)越来越流行。服务端提供API,APP端或者网页前端便可方便调用数据。用ShowDoc可以非常方便快速地编写出美观的API文档。
数据字典
一份好的数据字典可以很方便地向别人说明你的数据库结构,如各个字段的释义等。
说明文档
你完全可以使用showdoc来编写一些工具的说明书,也可以编写一些技术规范说明文档以供团队查阅。
分享与导出
响应式网页设计,可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成word文件,以便离线浏览。
权限管理
公开项目与私密项目
ShowDoc上的项目有公开项目和私密项目两种。公开项目可供任何登录与非登录的用户访问,而私密项目则需要输入密码验证访问。密码由项目创建者设置。
项目转让
项目创建者可以自由地把项目转让给网站的其他用户。
项目成员
你可以很方便地为ShowDoc的项目添加、删除项目成员。项目成员可以对项目进行编辑,但不可转让或删除项目(只有项目创建者才有权限)

1

szm. 复制链接去分享

现在基本上养成了用markdown写文档的习惯。之前用Word写文档,因为格式问题,可能需要纠结好长时间,之后就忘记自己要写的重点了(•́ω•̀ ٥)是真的;后来接触过markdown之后,发现格式控制可以如此简单,根本不需要工具栏,获得焦点之后键盘可以搞定全部,并且文档迁移也不用担心格式会乱掉,Word换到不同版本的office上时,各种格式错乱会让你疯掉的。
git作为版本控制工具,配合markdown来说简直是神器,再也不用担心每次改动后备份过多不知道改了什么,这点Word就相差太远了,毕竟git只对文本敏感。
markdown另一个好处就是作为纯文本,就算不渲染也可以很好的理解,Word么,你不装个office也要有个WPS吧,所以,我选择markdown。

1

xmjomax 复制链接去分享

使用markdown写文档,能简单的少去关注格式问题,git 提交方便

1

keller.zhou 复制链接去分享

用showdoc写合作的文档,showdoc用在it行业感觉还是蛮流行的,他也是基于markdown编辑器,无论是编辑还是阅读体验都极佳很棒。

ShowDoc就是一个非常适合IT团队的在线文档分享工具,它可以加快团队之间沟通的效率。

API文档

随着移动互联网的发展,BaaS(后端即服务)越来越流行。服务端提供API,APP端或者网页前端便可方便调用数据。用ShowDoc可以非常方便快速地编写出美观的API文档。

数据字典

一份好的数据字典可以很方便地向别人说明你的数据库结构,如各个字段的释义等。

说明文档

你完全可以使用showdoc来编写一些工具的说明书,也可以编写一些技术规范说明文档以供团队查阅。

分享与导出

响应式网页设计,可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成word文件,以便离线浏览。

权限管理

公开项目与私密项目

ShowDoc上的项目有公开项目和私密项目两种。公开项目可供任何登录与非登录的用户访问,而私密项目则需要输入密码验证访问。密码由项目创建者设置。

项目转让

项目创建者可以自由地把项目转让给网站的其他用户。

项目成员

你可以很方便地为ShowDoc的项目添加、删除项目成员。项目成员可以对项目进行编辑,但不可转让或删除项目(只有项目创建者才有权限)

1

sunny-sunny 复制链接去分享

confulence 也就是wiki

1

strangeen 复制链接去分享

自从会了markdown就没用过其他的了,文档也是跟项目的,所以文档就放源码中,再用git和github管理,简直是天作之合,MD用一个叫小书匠的软件编辑,还不错的一款软件

1

redfire 复制链接去分享

为了多平台同步,使用有道云笔记多些,其内置的markdown因高效快捷,也是我的写作主力

1

decline 复制链接去分享

一直用的是markdown与git,方便快捷,实时同步,历史记录想看就看!

1

青枫14 复制链接去分享

markdown 大法好,用git做版本控制,如果需要转PDF或者doc则用pandoc进行转换,方便高效 😄

5