写文档经验分享

作者: 李强 时间: 2018/05/16

1.概述

刚开始写文档的时候,我一直被一个问题困扰,看了代码.学了东西,要不要整理成文档,很多方面的文档, 别人都写过,而且还比自己写的完善,后来想明白了,书写文档分两种:

  • 此类文档别人写过,自己书写是对自己成长的一种记录,这类文档是写给自己看的;
  • 别人没有写过,或者自己比别人写的更好,这种文档是可以分享给别人多看的;

坚定了写文档的信念之后,问题就会转换成写什么,怎么写的问题,我的理解是:

  • 写什么在于学到了什么新知识,get 到了什么新技能;
  • 怎么写的问题,在网上会有非常多的介绍,比如:知乎.选择自己适合的就行;

我常用到的软件的分享:

  • git,Github
  • vim + bundle + python-vim-instant-markdown
  • Astah
  • draw.io
  • Atom

2.各种软件的使用

2.1 git,Github

使用git + Github 能够解决以下问题:

  • 文档的实时备份,不怕丢失;
  • 公司 + home 协同办公;
  • 如果你够牛,有很多人follow,这样可以上关注你的人及时看到你的最新文档;

2.2 vim + bundle + python-vim-instant-markdown

书写文档,首选markdown格式.推荐使用vim + bundle + python-vim-instant-markdown.bundle是插件管理器,vim + bundle也简称为Vundle. 它可以帮助实时查看文档显示情况. 如果你写的文档是这个样子: 写文档经验分享 - 图1

在vim里输入命令:Instantmd,在默认浏览器里面就可以看到,是这个样子的: 写文档经验分享 - 图2

当然为了能愉快的书写markdown文档,需要使用半个小时把markdown的基本语法学习一下.

2.3 Astah

作为一个程序员,免不了会画时序图之类的图,Astah就是用来干这个的.Astah是一款日本软件开发者的作品,分Community和Professional两款,Community提供基本功能,是免费的.

Astah官网; http://astah.net/

软件打开界面是这个样子的: 写文档经验分享 - 图3 可以画出这样子的时序图来: 写文档经验分享 - 图4

2.4 draw.io

除了时序图,当然还可能会用到流程图,android界面图,draw.io是google推出的,有网页版,和客户端版本.

draw.io网址: https://www.draw.io/

打开的界面: 写文档经验分享 - 图5 可以画Android的界面: 写文档经验分享 - 图6

2.5 Atom

Atom是github推出的一款软件,据说是21世纪的编辑器,与vim,Emacs比肩.书写文档: 写文档经验分享 - 图7

Atom有丰富的插件,而且界面比vim也要好看不少,功能也是非常的强大.