大多数开源项目开发者只关注于软件的质量,而常常忘记编写高品质的文档。但是,文档的好坏对于一个项目的成功有着至关重要的作用,它可以帮助用户快速了解这个项目,或在用户的使用过程中提供一些帮助。
然而,有很多开源项目的文档令人失望,主要表现在以下几个方面。
1. 缺乏一个良好的README或介绍
README可以使潜在用户对你的项目有一个初步、快速的了解,如果该项目在GitHub上,README文件会自动显示在该项目的主页。如果你想一下子吸引住用户,并让他们继续探索你的项目,那么一个好的介绍必不可少。如果介绍很糟糕,这些用户可能不会再回来了。
README文件至少应该包含:
- 项目用途
- 针对人群
- 运行的平台或硬件
- 重要依赖
- 如何安装,或更深层次的东西
项目README必须要针对那些从来没听说过你的项目的人来写。比如,项目中有一个计算Levenshtein距离的模块,你不要想当然地认为每个正在读README的人都知道Levenshtein是什么东西。你应该说明一下,并加上相关详细信息的链接,便于人们进一步探索。
在介绍一个新东西时,不要再引入其他的新东西,比如“NumberDoodle类似于BongoCalc,但更好”,人们或许压根不知道BongoCalc。
2. 没有在线提供文档
项目的文档必须能够在谷歌中查找到,因此,要确保你的文档在线可用。
我之前发布了一个开源项目,令我恼火的是,用户经常给我发邮件问一些我已经在FAQ中回答过的问题,后来我才发现,我没有将FAQ放在网站上。这是一个比较容易犯的错误,因为作者没有站在用户的角度考虑问题。
3. 只提供在线文档
你不能不提供在线文档,但同时也不能只提供在线文档。有些项目最终版本中没有附上文档,或者包含了项目开发阶段的不完整的文档,而将最终文档放在网上,这给无网络的用户,造成了一定的困扰。
比如,Solr项目,有一个非常全面的Wiki(文档),但是提供下载的却是一个2200页的自动生成的API Javadocs,其中针对最终用户的唯一的文档是一个单页的教程。
PHP语言包也没有附带任何文档,如果你想要文档,你必须到一个单独的页面。糟糕的是,只提供下载核心文档,并且还没有对用户有帮助的注释。
开源项目不能想当然地认为用户都能上网。你也不能让用户过分依赖于项目网站。在过去几个月中,我已经发现Solr wiki宕机至少两次了,而我当时正急需解决一个棘手的配置问题。
这一方面做的比较好的是Perl和其CPAN模块库。每个模块文档都以一种易于阅读的超链接格式提供在search.cpan.org和metacpan.org上。对于离线环境,每个模块文档嵌入在代码本身上,当用户安装模块时,会自动创建本地文档作为说明手册。用户也可以在Shell中使用perldoc Module::Name命令来获取文档。无论是在线或是离线,你都可以使用。
4. 文档没有自动安装
这通常是安装包创建者的错。比如,在Ubuntu Linux中,Perl语言的文档时一个独立的、可选的包,用户在安装时可能会遗漏掉这个选项。尽管节省了几MB的磁盘空间,但用户在需要时无法及时找到。
5. 缺少截图
有时候,一张图片胜过千言万语。
一个屏幕截图,可以帮助用户直观地比较操作结果,看是否正确地完成了各项任务,或轻松地找出哪里出现了问题。
现在,使用视频来介绍项目也变得普遍,视频可以显示一个复杂过程的步骤。比如Plone项目,有一个专门网站来提供视频教程。但是,视频还无法取代屏幕截图,因为用户无法通过视频快速找到某些内容(需要一点一点看),且视频无法被谷歌图片搜索收录,屏幕截图可以。
6. 缺乏现实例子
对于基于代码的项目,截图固然不错,但给出一个实例更实用。这些例子不应该是抽象的,而是来自现实世界中的。开发者应该花时间创建一个相关的例子,来向用户展示该项目是如何解决问题的。
正如Apache项目的Rich Bowen所说,“一个正确的、功能齐全的、经过测试的、有注释的例子,胜过一页的乏味介绍。”
7. 缺少链接和参考
不要认为你要解释的内容是文档的一部分,或者用户已经在前面读过,或者知道它们在哪里,就无需再使用超链接。比如,你的项目中有一部分代码作用是操作frobbitz对象,你有必要解释一下frobbitz对象,或链接到相关页面。
8. 不考虑新用户
编写文档的时候,不要认为一些用户已经知道一些东西而不去详细介绍。你应该考虑到新用户,并用一个单独的页面、最好的例子,来让新用户快速了解你的项目。
9. 不听用户的反馈
你应该积极听取使用你软件的用户的建议和需求,比如“如果有一个关于数据库驱动程序安装的介绍或链接就好了,这将帮助我安装这个程序”。
根据用户的反馈,创建一个常见问题。并经常关注其他一些网站或论坛,如StackOverflow,并创建一个Google Alert,来了解互联网上针对你的项目的讨论。
10. 不接受用户输入
如果你的项目有足够大的用户群,那么你可以考虑让用户能够直接将意见写到文档中。我见过最好的例子是PHP,每一页文档都允许经过身份验证的用户在页面中进行注释,或添加非核心文档例子。
这些内容需要维护,因为随着时间的推移,会出现一些过时的注释,这些需要被淘汰。
11. 必须安装后才能了解项目的用途
每个软件项目都需要有一个功能列表和页面截图,如果是纯粹的代码项目,比如一个库,也应该有一个示例页面。
12. 依赖于文档自动生成
大多时候,软件开发者会使用自动化的文档生成系统,来代替自己的工作。他们忘记了还需要手动写其他部分。
最坏的情况是,changelog中除了一些提交信息外没有任何内容。changelog应该列出新的功能、错误修复以及潜在的兼容性问题,它的目标群体是最终用户。而提交日志是给开发者看的。
13. 以傲慢的态度对待小白用户
不要对用户的问题都报以“RTFM(Read the Freaking Manual,去读那些TMD手册)”的态度,这可能会吓走一批潜在的用户。
如果用户的问题可以在文档中找到,但他们没有这样做,不要认为这是愚蠢的。有可能是因为你的文档写得糟糕,难以阅读,或者不完整。你需要耐心地改善“入门”章节,说明软件的目的是什么,或者给用户指明在哪里可以找到相关的信息。
英文原文:13 Things People Hate about Your Open Source Docs

“你的组织要求你更改PIN消息”将显示在登录屏幕上。当在使用基于组织的帐户设置的电脑上达到PIN过期限制时,就会发生这种情况,在该电脑上,他们可以控制个人设备。但是,如果您使用个人帐户设置了Windows,则理想情况下不应显示错误消息。虽然情况并非总是如此。大多数遇到错误的用户使用个人帐户报告。为什么我的组织要求我在Windows11上更改我的PIN?可能是您的帐户与组织相关联,您的主要方法应该是验证这一点。联系域管理员会有所帮助!此外,配置错误的本地策略设置或不正确的注册表项也可能导致错误。即

Windows11将清新优雅的设计带到了最前沿;现代界面允许您个性化和更改最精细的细节,例如窗口边框。在本指南中,我们将讨论分步说明,以帮助您在Windows操作系统中创建反映您的风格的环境。如何更改窗口边框设置?按+打开“设置”应用。WindowsI转到个性化,然后单击颜色设置。颜色更改窗口边框设置窗口11“宽度=”643“高度=”500“>找到在标题栏和窗口边框上显示强调色选项,然后切换它旁边的开关。若要在“开始”菜单和任务栏上显示主题色,请打开“在开始”菜单和任务栏上显示主题

默认情况下,Windows11上的标题栏颜色取决于您选择的深色/浅色主题。但是,您可以将其更改为所需的任何颜色。在本指南中,我们将讨论三种方法的分步说明,以更改它并个性化您的桌面体验,使其具有视觉吸引力。是否可以更改活动和非活动窗口的标题栏颜色?是的,您可以使用“设置”应用更改活动窗口的标题栏颜色,也可以使用注册表编辑器更改非活动窗口的标题栏颜色。若要了解这些步骤,请转到下一部分。如何在Windows11中更改标题栏的颜色?1.使用“设置”应用按+打开设置窗口。WindowsI前往“个性化”,然

您是否在Windows安装程序页面上看到“出现问题”以及“OOBELANGUAGE”语句?Windows的安装有时会因此类错误而停止。OOBE表示开箱即用的体验。正如错误提示所表示的那样,这是与OOBE语言选择相关的问题。没有什么可担心的,你可以通过OOBE屏幕本身的漂亮注册表编辑来解决这个问题。快速修复–1.单击OOBE应用底部的“重试”按钮。这将继续进行该过程,而不会再打嗝。2.使用电源按钮强制关闭系统。系统重新启动后,OOBE应继续。3.断开系统与互联网的连接。在脱机模式下完成OOBE的所

任务栏缩略图可能很有趣,但它们也可能分散注意力或烦人。考虑到您将鼠标悬停在该区域的频率,您可能无意中关闭了重要窗口几次。另一个缺点是它使用更多的系统资源,因此,如果您一直在寻找一种提高资源效率的方法,我们将向您展示如何禁用它。不过,如果您的硬件规格可以处理它并且您喜欢预览版,则可以启用它。如何在Windows11中启用任务栏缩略图预览?1.使用“设置”应用点击键并单击设置。Windows单击系统,然后选择关于。点击高级系统设置。导航到“高级”选项卡,然后选择“性能”下的“设置”。在“视觉效果”选

在Windows11上的显示缩放方面,我们都有不同的偏好。有些人喜欢大图标,有些人喜欢小图标。但是,我们都同意拥有正确的缩放比例很重要。字体缩放不良或图像过度缩放可能是工作时真正的生产力杀手,因此您需要知道如何对其进行自定义以充分利用系统功能。自定义缩放的优点:对于难以阅读屏幕上的文本的人来说,这是一个有用的功能。它可以帮助您一次在屏幕上查看更多内容。您可以创建仅适用于某些监视器和应用程序的自定义扩展配置文件。可以帮助提高低端硬件的性能。它使您可以更好地控制屏幕上的内容。如何在Windows11

屏幕亮度是使用现代计算设备不可或缺的一部分,尤其是当您长时间注视屏幕时。它可以帮助您减轻眼睛疲劳,提高易读性,并轻松有效地查看内容。但是,根据您的设置,有时很难管理亮度,尤其是在具有新UI更改的Windows11上。如果您在调整亮度时遇到问题,以下是在Windows11上管理亮度的所有方法。如何在Windows11上更改亮度[10种方式解释]单显示器用户可以使用以下方法在Windows11上调整亮度。这包括使用单个显示器的台式机系统以及笔记本电脑。让我们开始吧。方法1:使用操作中心操作中心是访问

在iOS17中,Apple为其移动操作系统引入了几项新的隐私和安全功能,其中之一是能够要求对Safari中的隐私浏览选项卡进行二次身份验证。以下是它的工作原理以及如何将其关闭。在运行iOS17或iPadOS17的iPhone或iPad上,如果您在Safari浏览器中打开了任何“无痕浏览”标签页,然后退出会话或App,Apple的浏览器现在需要面容ID/触控ID认证或密码才能再次访问它们。换句话说,如果有人在解锁您的iPhone或iPad时拿到了它,他们仍然无法在不知道您的密码的情况下查看您的隐私


Hot AI Tools

Undresser.AI Undress
AI-powered app for creating realistic nude photos

AI Clothes Remover
Online AI tool for removing clothes from photos.

Undress AI Tool
Undress images for free

Clothoff.io
AI clothes remover

AI Hentai Generator
Generate AI Hentai for free.

Hot Article

Hot Tools

PhpStorm Mac version
The latest (2018.2.1) professional PHP integrated development tool

Dreamweaver Mac version
Visual web development tools

SecLists
SecLists is the ultimate security tester's companion. It is a collection of various types of lists that are frequently used during security assessments, all in one place. SecLists helps make security testing more efficient and productive by conveniently providing all the lists a security tester might need. List types include usernames, passwords, URLs, fuzzing payloads, sensitive data patterns, web shells, and more. The tester can simply pull this repository onto a new test machine and he will have access to every type of list he needs.

DVWA
Damn Vulnerable Web App (DVWA) is a PHP/MySQL web application that is very vulnerable. Its main goals are to be an aid for security professionals to test their skills and tools in a legal environment, to help web developers better understand the process of securing web applications, and to help teachers/students teach/learn in a classroom environment Web application security. The goal of DVWA is to practice some of the most common web vulnerabilities through a simple and straightforward interface, with varying degrees of difficulty. Please note that this software

MinGW - Minimalist GNU for Windows
This project is in the process of being migrated to osdn.net/projects/mingw, you can continue to follow us there. MinGW: A native Windows port of the GNU Compiler Collection (GCC), freely distributable import libraries and header files for building native Windows applications; includes extensions to the MSVC runtime to support C99 functionality. All MinGW software can run on 64-bit Windows platforms.
