技术文档

程序员编写技术文档的新手指南

作者:admin   来源:未知

  我觉察一开端从利己的角度来阐明这个题目会比拟有吸引力。写文档最好的原因便是你将会正在 6 个月后利用你的代码。你 6 个月前写的代码跟别人写的代码对你来说日常没有什么区别。你将会带着一种熟习的感到读你的代码。然后一种不良的征兆默默迫临,你觉察写代码的人毫无体味,毫无灵巧。

  当你读完几个月前很简略易懂或者取巧的代码之后,你就会开端怜悯你的用户。只须我写下为什么我要这么做,生涯就会变得如斯简略。文档能让你纪录代码为什么如此写的缘故。同样地,代码诠释阐明了为什么,而不是若何做,文档也是如此。

  你依然写了一段代码,而且揭橥了它。你如此做是由于你以为别人也许以为它有效。然则,人们需求先明晰为什么你的代码对他们也许有效,才会决意利用它。文档能够告诉人们这个项目对他们有效。

  惟有少数人会深化考虑你的代码而且利用它。简直没人会利用你的代码,除非它有好的文档。假若你真的热爱你的项目,给它写文档,让其他人利用它。

  开源项目是拥有魔力的,对吗?你揭橥了代码,然后 code gnomes 展示而且让你的代码更好。

  当你揭橥代码的光阴会有一种怪僻的感到发生。它通过百般体例展示,但老是能让你兴奋不已。有人正在利用我的代码?这是一种同化了畏缩和兴奋的感到。

  写好的文档不妨减轻这种畏缩。许多畏缩来自于给全国创设东西。我最爱好的闭于这个题目的引文如下所示。

  文档也为你项宗旨第一次进献供应平台。许多人平素没有为开源项目进献过,让他们修削代码比修削文档恐怖得多。假若你没有文档,你将落空这类文档进献者。

  有一个陈旧的到底:把东西写下来帮帮你更好地思虑。思想里发生一个听起来不错的念法很容易,然则把念法写到纸上就需求思念上的升华。

  写文档能擢升代码的安排。正在纸上接洽你的API和安排决意能够让你用一种改变式的体例思虑它们。它又有一个不错的副效用:让别人遵从你本来的妄念进献代码。

  写文档跟大大批人体验过的写作体例差别。技巧写作是一种非与生俱来的艺术。写文档将会是你成为更好的技巧写作家这条道的起始,行为序次员,这是一个有效的妙技。

  写作会跟着时刻的流逝变得更容易。假若你好几个月没写东西,再次动笔就会变得越发穷困。边做项目边写文档将会让你依旧一个合理写作节律。

  简略的开端是博得本质成就的最好体例。我将会供应一条平展的道给你走,正在你有了根基的念法之后,你能够扩张限度。这些用具很健旺而且容易利用。这将移除写作的波折。

  这篇作品中的例子正在 Markdown 和 reStructuredText 中都是有用的。reStructuredText 有一点难用,然则更健旺。我举荐你两个都看看,然后决意哪个你念要用。

  做为序次员咱们生涯中纯文本的全国里。咱们的文档用具不应不同。咱们念要能把纯文本转化成美丽的 HTML 的用具。咱们又有极少最好的跟踪文献变革的用具。为什么咱们写文档的光阴会放弃利用这些用具?这套处事流是健旺的,而且对开辟者来说很熟习的。

  上面的文字将衬托成题目,下面带着列表。URLs 将会被自愿超链接。这写起来很容易,不仅行为纯文本蓄谋义,并且还能很好的衬托成 HTML。

  你第一个应当写的文档是 README。假若你供应了相宜的扩展名,代码托管供职会自愿把你的 README 衬托成 HTML。它也是大大批用户跟你的项宗旨第一次互动。是以,一个牢靠的 README 对你的项目异常有效。

  用户是指那些只是念利用你的代码,而不管重视它若何处事的人。开辟者是指那些念要给你的代码做进献的人。

  许多人会通过你的文档搞清爽你的项目是什么。有人会提到它,有人会随机地用 Google 搜求一个短语。你应当阐明你的项目做了什么和它存正在的事理。Fabric这方面做的很好。

  人们有光阴爱好浏览源代码。他们也许对归档他们觉察的代码 BUG 感意思。尽也许地让那些念要为项目做进献的人做这件事很容易。我以为Python Guide做得很好,由于它有指向代码个人的链接。

  许多人会有不异的题目。假若题目无间产生,你应当适应地修削你的文档或者代码来管理题目。然则老是有极少往往被问的闭于项宗旨题目,不行变革的的事故等。把这些纪录正在文档中,而且使其依旧最新。FAQs 日常会过期,但当它们被很好的爱护时,它们便是黄金资源。Tastypie做得很好,它把 FAQs 整饬成“Cookbook”。

  邮件列表?IRC 频道?文档要纪录若何获取帮帮和跟项目社区调换。Django这方面做得很好。

  正在项目中,人们日常有若何干事情的准绳。你应当纪录正在文档上,以便于别人写代码时能适当项宗旨准绳。Open Comparison这方面做的很好。

  一朝人们决意利用你的代码,他们需求明晰若何获取它和运转它。希望你的装置指令惟有几行用于根基利用。假若有须要,给出供应更多讯息和分析的页面链接。我以为Read the Docs中咱们做得很好。

  BSD?MIT? GPL? 这些证书也许对你来说没什么,然则利用你代码的人会很重视这个。商量一下你念要用什么证书揭橥你的项目,务必遴选一个互联网上的标许可可证。

  正在你听从上面的指南之后,咱们信托你的项目将会胜利。进一步的参考原料,查看这篇作品若何爱护一个开源项目。

技术文档

联系我们

CONTACT US

联系人:张先生

手机:13988889999

电话:020-66889888

邮箱:admin@baidu.com

地址:广东省广州市番禺经济开发区58号