开源最前线(ID:OpenSourceTop) 猿妹综合编译 链接:https://dzone.com/articles/programmers-hate-writing-documentation-these-4-to
对于一般的程序员来说,花费数小时来创建代码或修改现有代码只是一天工作中的一部分,简而言之,当程序员忙于他们最新的项目时,他们会把自己与外界隔绝,这种刻板印象还是有一定道理的。
但是你没发现的是其实很多程序员还需要是保存关于他们的代码如何工作的文档,事实上,很多程序员都不愿意写文档,编程心理学的作者和专家Gerald Weinberg将其总结为“编程的蓖麻油”——换句话说,这是一件对他们有好处但他们讨厌做的事情。
如果没有一个好的文档,关于软件如何运行的信息就会缺乏,现如今,许多开发者最多就是在他们编写的代码中留下一个基本的路线图,但这依然不能解决代码的终端用户的问题,因此,软件开发人员必须养成良好的文档记录习惯,这样你的黑盒代码才不会对其他人来说是一个谜。
今天,和大家推荐4个不错的在线软件文档工具:
1、GitHub Pages
现在大多程序员都会使用通用代码库Github,所以对于希望保存文档的程序员来说,Github是一个不错的选择,尽管很多人只是利用代码库中的readme功能来为项目提供简单的操作指南,但这并非是最好的办法。
GitHub pages,它的项目页面(包括文档和手册)提供了一个专用的托管平台。它直接与所有GitHub存储库交互,允许开发人员以更新代码的方式更新文档。最关键的是,用户可以使用Jekyll,将纯文本标记转换成成熟的静态网站,而不需要额外的编程。
地址:https://pages.github.com/
2、Read the Docs
顾名思义,Read the Docs为开发人员提供了一个集中的平台来保存文档,这样用户就可以直接阅读文档了。它的工作原理有点类似GitHub pages,因为开发人员可以从他们喜欢的版本控制系统(包括Git、Bazaar、Mercurial等)中推送文档更新。
不过,Read the Docs最好的部分还是它的灵活性,因此开发人员可以自动化大部分的文档创建过程,这样一来就可以节省大量的时间,最重要的是,平台上的所有内容都以多种格式向公众开放,形式包括pdf、HTML,电子阅读等。
地址:https://readthedocs.org/
3、Tettra
虽然不是严格地作为软件文档平台,但是作为一个成熟的知识库,Tettra仍然是一个非常好的软件文档工具。当一个项目设计到多个程序员,而非技术用户想要了解整个项目细节的时候,Tettra最为适用。对于大多数软件开发人员来说,Tettra在记录与他们工作相关的常见问题的答案时表现最为突出。
地址:https://tettra.com/
4、Apiary
尽管软件文档始终被认为是关键任务,但是有一种类型的文档是任何开发人员都不能忽视的——API文档,由于它们是软件中最容易被外部用户发现的部分,所以当某些事情不清楚时,它们也会产生很多的问题。Apiary是一个平台,允许用户使用Markdown编写其文档,包括模拟API调用。此外,该平台允许用户测试API,换句话说,它既是一个文档工具也是一个测试平台。
地址:https://apiary.io/