首页 > 网站 > 建站经验 > 正文

程序员 新手指南之如何编写技术文档

2019-11-02 14:27:04
字体:
来源:转载
供稿:网友

 如何编写技术文档,编写技术文档,技术文档,程序员新手指南

  为什么要写文档?

  你将会在 6 个月后使用你的代码

  我发现一开始从利己的角度来解释这个问题会比较有吸引力。写文档最好的理由就是你将会在 6 个月后使用你的代码。你 6 个月前写的代码跟别人写的代码对你来说通常没有什么区别。你将会带着一种熟悉的感觉读你的代码。然后一种不良的预兆悄悄逼近,你发现写代码的人毫无经验,毫无智慧。

  当你读完几个月前很简单易懂或者取巧的代码之后,你就会开始同情你的用户。只要我写下为什么我要这么做,生活就会变得如此简单。文档能让你记录代码为什么这样写的原因。同样地,代码注释解释了为什么,而不是怎么做,文档也是这样。

  你想要别人使用你的代码

  你已经写了一段代码,并且发布了它。你这样做是因为你认为别人可能觉得它有用。但是,人们需要先知道为什么你的代码对他们可能有用,才会决定使用它。文档可以告诉人们这个项目对他们有用。

  如果人们不知道你项目存在的意义,他们不会使用它。

  如果人们不知道怎么安装你的程序,他们不会使用它。

  如果人们不知道怎么使用你的代码,他们不会使用它。

  只有少数人会深入研究你的代码并且使用它。几乎没人会使用你的代码,除非它有好的文档。如果你真的热爱你的项目,给它写文档,让其他人使用它。

  你需要别人的帮助

  开源项目是具有魔力的,对吗?你发布了代码,然后 code gnomes 出现并且让你的代码更好。

  当你发布代码的时候会有一种奇妙的感觉产生。它通过各种方式出现,但总是能让你兴奋不已。有人在使用我的代码?这是一种混合了恐惧和兴奋的感觉。

  我创造了价值!

  如果它出错了怎么办?!

  我是一个开源项目开发者了!

  天哪,别人在使用我的代码。。。

  写好的文档能够减轻这种恐惧。很多恐惧来自于给世界创造东西。我最喜欢的关于这个问题的引文如下所示:

  恐惧来自于你做着重要的事情。

  如果你在做不让你恐惧的事情,那么它对你或者世界都没有益处。

  恭喜你感到恐惧!它意味着你在做重要的事情。

  实际上,不完全是这样。

  开源项目确实令人感到惊奇,但它同样必须符合现实世界的规则。你必须有付出,才有收获。

  在你为项目付出大量工作之后,才能获得贡献。

  在你的项目有用户之后,才能获得贡献。

  在你的项目有文档之后,才能获得贡献。

  文档也为你项目的第一次贡献提供平台。很多人从来没有为开源项目贡献过,让他们修改代码比修改文档可怕得多。如果你没有文档,你将失去这类文档贡献者。

  文档让你的代码更好

  有一个古老的事实:把东西写下来帮助你更好地思考。头脑里产生一个听起来不错的想法很容易,但是把想法写到纸上就需要思想上的升华。

  写文档能提升代码的设计。在纸上讨论你的API和设计决定可以让你用一种更正式的方式思考它们。它还有一个不错的副作用:让别人按照你原来的意图贡献代码。

  你想成为一个更好的写作者。

  写文档跟大多数人体验过的写作方式不同。技术写作是一种非与生俱来的艺术。写文档将会是你成为更好的技术写作者这条路的起点,作为程序员,这是一个有用的技能。

  写作会随着时间的流逝变得更容易。如果你好几个月没写东西,再次动笔就会变得更加困难。边做项目边写文档将会让你保持一个合理写作节奏。

  用什么工具写作

  简单的开始是取得实际成果的最好方式。我将会提供一条平坦的路给你走,在你有了基本的想法之后,你可以扩大范围。这些工具很强大并且容易使用。这将移除写作的障碍。

发表评论 共有条评论
用户名: 密码:
验证码: 匿名发表