仓酷云

标题: PHP教程之开源项目文档13处应躲避 [打印本页]

作者: 萌萌妈妈 时间: 2015-1-16 22:16
标题: PHP教程之开源项目文档13处应躲避
PHP的理解是新手最难迈过的一道门槛，不过你应该感到幸运的是PHP已经最大极限的为了新手而努力了，如果你学过其他的语言，也许会觉得PHP的确相当的简单，但是如果你之前什么都没学过，那么阿弥陀佛，硬着头皮琢磨吧。年夜多半开源项目开辟者只存眷于软件的质量，而经常健忘编写高品德的文档。可是，文档的优劣关于一个项目标乐成有着相当主要的感化，它能够匡助用户疾速懂得这个项目，或在用户的利用过程当中供应一些匡助。

但是，有良多开源项目标文档使人扫兴，次要体现在以下几个方面。

1.缺少一个优秀的README或先容

README可使潜伏用户对你的项目有一个开端、疾速的懂得，假如该项目在GitHub上，README文件会主动显现在该项目标主页。假如你想一会儿吸引住用户，并让他们持续探究你的项目，那末一个好的先容必不成少。假如先容很糟，这些用户大概不会再返来了。

README文件最少应当包括：

项目用处
针对人群
运转的平台或硬件
主要依附
怎样安装，或更深条理的器材

项目README必需要针对那些历来没传闻过你的项目标人来写。好比，项目中有一个盘算Levenshtein间隔的模块，你不要想固然地以为每一个正在读README的人都晓得Levenshtein是甚么器材。你应当申明一下，并加上相干具体信息的链接，便于人们进一步探究。

在先容一个新器材时，不要再引进其他的新器材，好比“NumberDoodle相似于BongoCalc，但更好”，人们也许压根不晓得BongoCalc。

2.没有在线供应文档

项目标文档必需可以在谷歌中查找到，因而，要确保你的文档在线可用。

我之前公布了一个开源项目，令我末路火的是，用户常常给我发邮件问一些我已在FAQ中回覆过的成绩，厥后我才发明，我未将FAQ放在网站上。这是一个对照简单犯的毛病，由于作者没有站在用户的角度思索成绩。

3.只供应在线文档

你不克不及不供应在线文档，但同时也不克不及只供应在线文档。有些项目终极版本中没有附上文档，大概包括了项目开辟阶段的不完全的文档，而将终极文档放在网上，这给无收集的用户，形成了必定的困扰。

好比，Solr项目，有一个十分周全的Wiki（文档），可是供应下载的倒是一个2200页的主动天生的APIJavadocs，个中针对终极用户的独一的文档是一个单页的教程。

PHP言语包也没有附带任何文档，假如你想要文档，你必需到一个独自的页面。糟的是，只供应下载中心文档，而且还没有对用户有匡助的正文。

开源项目不克不及想固然地以为用户都能上彀。你也不克不及让用户太过依附于项目网站。在已往几个月中，我已发明Solrwiki宕机最少两次了，而我事先正急需办理一个辣手的设置成绩。

这一方面做的对照好的是Perl和其CPAN模块库。每一个模块文档都以一种易于浏览的超链接格局供应在search.cpan.org和metacpan.org上。关于离线情况，每一个模块文档嵌进在代码自己上，当用户安装模块时，会主动创立当地文档作为申明手册。用户也能够在Shell中利用perldocModule::Name命令来猎取文档。不管是在线或是离线，你都可使用。

4.文档没有主动安装

这一般是安装包创立者的错。好比，在UbuntuLinux中，Perl言语的文档时一个自力的、可选的包，用户在安装时大概会漏掉失落这个选项。只管节俭了几MB的磁盘空间，但用户在必要时没法实时找到。

5.短少截图

偶然候，一张图片赛过千言万语。

一个屏幕截图，能够匡助用户直不雅地对照操纵了局，看是不是准确地完成了各项义务，或轻松地找出那里呈现了成绩。

如今，利用视频来先容项目也变得广泛，视频能够显现一个庞大历程的步骤。好比Plone项目，有一个专门网站来供应视频教程。可是，视频还没法代替屏幕截图，由于用户没法经由过程视频疾速找到某些内容（必要一点一点看），且视频没法被谷歌图片搜刮收录，屏幕截图能够。

6.缺少实际例子

关于基于代码的项目，截图当然不错，但给出一个实例更有用。这些例子不该该是笼统的，而是来自实际天下中的。开辟者应当花工夫创立一个相干的例子，来向用户展现该项目是怎样办理成绩的。

正如Apache项目标RichBowen所说，“一个准确的、功效完全的、经由测试的、有正文的例子，赛过一页的有趣先容。”

7.短少链接和参考

不要以为你要注释的内容是文档的一部分，大概用户已在后面读过，大概晓得它们在那里，就无需再利用超链接。好比，你的项目中有一部分代码感化是操纵frobbitz工具，你有需要注释一下frobbitz工具，或链接到相干页面。

8.不思索新用户

编写文档的时分，不要以为一些用户已晓得一些器材而不往具体先容。你应当思索到新用户，并用一个独自的页面、最好的例子，来让新用户疾速懂得你的项目。

9.不听用户的反应
你应当主动听取利用你软件的用户的倡议和需求，好比“假如有一个关于数据库驱动程序安装的先容或链接就行了，这将匡助我安装这个程序”。

依据用户的反应，创立一个罕见成绩。并常常存眷其他一些网站或论坛，如StackOverflow，并创立一个GoogleAlert，来懂得互联网上针对你的项目标会商。

10.不承受用户输出

假如你的项目有充足年夜的用户群，那末你能够思索让用户可以间接将定见写到文档中。我见过最好的例子是PHP，每页文档都同意经由身份考证的用户在页面中举行正文，或增加非中心文档例子。

这些内容必要保护，由于跟着工夫的推移，会呈现一些过期的正文，这些必要被减少。

11.必需安装后才干懂得项目标用处

每一个软件项目都必要有一个功效列表和页面截图，假如是地道的代码项目，好比一个库，也应当有一个示例页面。

12.依附于文档主动天生

年夜多时分，软件开辟者会利用主动化的文档天生体系，来取代本人的事情。他们健忘了还必要手动写其他部分。

最坏的情形是，changelog中除一些提交信息外没有任何内容。changelog应当列出新的功效、毛病修复和潜伏的兼容性成绩，它的方针群体是终极用户。而提交日记是给开辟者看的。

13.以狂妄的立场看待小白用户

不要对用户的成绩都报以“RTFM（ReadtheFreakingManual，往读那些TMD手册）”的立场，这大概会吓走一批潜伏的用户。

假如用户的成绩能够在文档中找到，但他们没有如许做，不要以为这是愚昧的。有多是由于你的文档写得糟，难以浏览，大概不完全。你必要耐烦地改良“进门”章节，申明软件的目标是甚么，大概给用户指明在那里能够找到相干的信息。

英文原文：13ThingsPeopleHateaboutYourOpenSourceDocs
实现固定数量的几张图片的上传；再如调试软件ZendStudio的使用，看了很多次老师的应用，但总感觉用的不顺手，不懂那么多的数据值，到底哪一个才是真正的问题所在；还有如数据库语句的封装，我只会用简单的函数来进行封装。

作者: 活着的死人 时间: 2015-1-17 05:32
写js我最烦的就是ie和firefox下同样的代码结果显示的结果千差万别，还是就是最好不要用遨游去调试，因为有时候遨游是禁用js的，有可能代码是争取结果被遨游折腾的认为是代码写错。

作者: 灵魂腐蚀 时间: 2015-1-20 13:21
我还是推荐用firefox ，配上firebug 插件调试js能省下不受时间。谷歌的浏览器最好也不少用，因为谷歌的大侠们实在是太天才啦，把一些原来的js代码加了一些特效。

作者: 柔情似水 时间: 2015-1-29 07:35
要进行开发，搭建环境是首先需要做的事，windows下面我习惯把环境那个安装在C盘下面，因为我配的环境经常出现诡异事件，什么事都没做环境有的时候就不能用啦。

作者: 金色的骷髅 时间: 2015-2-6 00:02
在我安装pear包的时候老是提示，缺少某某文件，才发现那群extension 的排列是应该有一点的顺序，而我安装的版本的排序不是正常的排序。没办法我只好把那群冒号加了上去，只留下我需要使用的扩展。

作者: 若天明 时间: 2015-2-14 11:33
其实没啥难的，多练习，练习写程序，真正的实践比看100遍都有用。不过要熟悉引擎

作者: 蒙在股里 时间: 2015-3-4 05:54
本人接触php时间不长，算是phper中的小菜鸟一只吧。由于刚开始学的时候没有名师指，碰过不少疙瘩，呗很多小问题卡过很久，白白浪费不少宝贵的时间，在次分享一些子的学习的心得。

作者: 不帅 时间: 2015-3-11 17:39
没接触过框架的人，也不用害怕，其实框架就是一种命名规范及插件，学会一个框架其余的框架都很好上手的。

作者: 第二个灵魂 时间: 2015-3-19 04:14
如果你已经到这种程度了，那么你已经可以做我的老师了。其实php也分很多的区域，

作者: 小妖女 时间: 2015-3-27 07:36
我要在声明一下：我是个菜鸟！！我对php这门优秀的语言也是知之甚少。但是我要在这里说一下php在网站开发中最常用的几个功能：

欢迎光临仓酷云 (http://ckuyun.com/)