我们如何才能使软件文档变得更简单?

要编写有用而又平淡的文档,请清楚了解读者是谁,并专注于满足她的需求。

例如,编程工具和代码库的文档通常很好,因为开发人员和作者可以轻松地将自己想象在读者手中。

当提供信息的开发人员认为文档是一件繁琐的事,而分配了作者以使信息看起来有用时,便会创建最迟钝,最不可用的文档。 这样的文档通常是多用途的,并且侧重于描述产品,而不考虑公司管理层和销售人员以外的任何读者。 因此,如果您正在阅读浪费大量时间宣传产品的体系结构创新和市场定位的文档,但找不到有关如何使用产品的基本问题的答案,那么呆板可能会成为最少的问题。投诉。

对于除编程工具和代码库以外的软件,编写有用的(而不是乏味的)文档需要付出额外的努力。 读者必须有一个拥护者。 直接向用户出售软件的公司通常会提供良好的文档。 如果向其他公司出售软件的公司也执行可用性测试并获得用户和实施团队的反馈,则有时会提供良好的文档,特别是如果反馈中包含对文档的审阅。

除了企业文化方面,我关于编写有用的(而不是乏味的)文档的最佳建议是不要使读者对不适用的变体进行分类。 例如,如果您正在编写可在Windows或Linux上使用Oracle或DB2数据库的软件的安装说明,则不要创建主题,读者必须仔细阅读所有版本的说明。 而是为每个变体写一个单独的主题,或使用动态扩展文本来隔离特定于平台的步骤。

注意我的假设,即简单地显示有用信息并不乏味。 我已经看到了一些成功的尝试来减轻技术信息的尝试,但是没有很多。 我记得最奇怪的尝试是唐纳德·克努斯(Donald Knuth)的《 The TeXbook》,该书使用了漫画,路标和巧妙的措辞来减轻主题的负担。 (我仍然记得20多年后的“无限伸缩性胶水”。)但是我发现很难挖掘出修改TeX样式表所需的信息。 当我终于得到它的时候,我感觉好像我已经破解了一本咒语书中的代码。

感谢您的A2A。

我认为,斯蒂芬给出了一个非常彻底的答案。 他用以下评论打在了头上:

>当贡献信息的开发人员将文档视为琐事时,就会创建最迟钝,最少可用的文档

完美的描述方式。 您能做的最坏的事情是迫使开发人员首先编写自己不想编写的文档。 但是,如果我要研究为什么会发生这种情况,为什么开发人员不想编写文档,我认为最大的原因是:开发人员不会将文档视为花费时间的有效方法。

开发人员善变的小事情。 我们喜欢感到重要,创造更好的人性化工具。 不幸的是,我们也倾向于在工作环境中拥有一些最大的自负,这不利于我们将文档视为浪费时间。

我认为需要做的是改变我们对文档的看法,这里有一些想法:

1.编写多种类型的文档。 例如,如果您拥有可以集成的产品,请编写两个文档。 一种用于非技术人员,另一种用于技术人员。 这听起来可能违反直觉(两个比一个更好),但是如果您考虑一下,这是有道理的。 这类文档中最难的部分是使某些内容容易被非技术人员理解,同时也使开发人员和类似人员感兴趣。 如果您将文档分开,那么您可以专注于一种样式,并且不需要开发人员比他/她需要付出更多的努力:选择一种样式,编写文档。 选择下一个样式,编写另一个文档。

2.强制开发人员阅读更多文档。 我开始喜欢为自己的工作写文档的原因是您读过的一些最细微的东西,但是我在这里将其分享,因为它会有所帮助。 我正在使用某些第三方API,并且像往常一样,我在没有RTFM的情况下就开始使用它。 当您这样做,对不对? 所以我在沟里,我无法抓住自己的出路。 犹豫不决,我拿起了文档,瞧,这是我读过的最烂的东西。 我觉得读起来更糟。 我觉得很哑。 但是,这种经历使我有动力编写更好的文档。 现在,每次编写文档时,我都会牢记这一点,并且我想编写比遇到的更好的文档。 我对自己说:“这些家伙做错了什么?”然后我比他们做得更好。 这使我充满动力,并帮助我保持对终端游戏的关注:避免让其他开发人员经历我所经历的一切。

我认为这两件事将有助于解决开发人员觉得他们在浪费时间编写文档的问题。

引自python文档:

>>> def鹦鹉(电压,状态=’僵硬’,动作=’可见’):
…print(“ –这只鹦鹉不会”,动作,结束=”)
…print(“如果放进去”,电压,“通过它的伏特。”,结束=”)
…print(“ E’s,state,”!“)

>>> d = {“电压”:“四百万”,“状态”:“出血”,“动作”:“ VOOM”}
>>>鹦鹉(** d)
—如果您通过它放置400万伏特,这只鹦鹉不会发声。 E流血了!

因此,选择一个相关主题并进行大量引用。 (注意:在撰写此答案时,没有鹦鹉被杀死)。

你好,Dik Spekenbrink! 好问题。

幸运的是,对于我们程序员而言,代码是活的东西。 因此,最好的文档是实际的代码,例如测试用例,它们只有在与主应用程序代码保持最新时才能通过。 反之亦然:只有通过所有测试,才能接受主代码模块。

是的,当所有人(不仅是青少年)真正遵循TL; DR引理时,极限编程是一个好主意。

我认为对于非程序员,应该有一个类似的学科。 例如,以功能回归测试的形式应始终保持最新。

  • 定位点和准确的注释
  • 没有重复的东西
  • 图形化
  • GIF,动画将为现代文档提供帮助
  • 准确的措辞并澄清