Linux今天:Linux上网时间。




更多文档作家的提示(您也是,ACE编码器)

| | 评论(0)

上周我们学到了几个提示 为了编写更好的文档,并谈论为什么好的文档非常重要。这似乎是不言而喻的,但有些人没有收到消息:)。今天我们将谈谈让清除,精确的例子进行谈话,为什么严格的文字是如此重要。

不幸的计算机文档是如此简洁,看起来好像作者必须用这个词支付。虽然可以过度解释,但这几乎没有问题。通过计算机,我们主要在抽象概念中处理,因此拼写甚至似乎似乎看起来太明显和基本的细节,因为到了很多读者,他们不会是显而易见和基本的。

一张图片胜过千言万语,截图也是如此谈论的。对于命令行程序,它甚至比创建屏幕截图更容易,只需复制并粘贴文本。您希望尽可能地是文字,因为计算机要求精确的文字命令。他们无法读取你的意图或挥手,只有你的类型。

这是一个太简单的一个例子:

“使用p选项打印到屏幕,v选项以进行详细。”

这没关系,但这样做的方式使它变得清晰:

“使用P选项打印到屏幕,以及v选项的详细程度,如下所示:

$ foo -p -v

您可以组合这样的选项:

$ foo -pv.

增加VS的数量,最多四个,增加了冗长的水平,如下所示:

$ foo -pv.vvv“

这个简单的例子显示了许多重要细节:将命令作为一个未体居的用户运行,打击数为正确的破折号和案例。给出正确的命令输出的缩写示例也有助于,因此您的读者何时正确运行该命令。当他们不了解模糊的指示时,您的读者并不愚蠢,这是指示的缺陷。

计算机HOWTOS有两种有用的方法:一个是一个特定命令的所有选项的文字列表和解释,另一个是面向任务的方法。第一个是典型的男人页面,最好的男人页面还包括很多例子演示如何完成特定任务。例如,Man NMAP是一种漫长而深入的参考,既具有传统的简洁人员页格式,以及大量详细的博览会和面向任务的示例。

采用面向任务的方法是尤其有价值的,当您教导比单个自包含命令更复杂,例如将邮件或Web服务器放在一起。 UNIX / Linux具有串串串的传统,用于执行更大的任务,这是一种光滑,有效的定制和执行复杂任务的方法,但不足以拼写用户需要做些什么的传统工作。我会说Linux文档中最大的洞是这种HOWTO。

总是记住,每个人都开始作为初学者;没有人诞生知道这件事。众神善待患者,乐于助人的老师微笑。在这个小系列中,周四回来一个分期付款,如何获得编写Howtos的报酬。


评论和贡献



    (最大字符:4000)。剩下4000个字符。