使用 LogicalDOC 更好地跟踪文档版本，这是我们开源工具系列中的第 12 个工具，它将使你在 2019 年更高效。

每年年初似乎都有疯狂的冲动想提高工作效率。新年的决心，渴望开启新的一年，当然，“抛弃旧的，拥抱新的”的态度促成了这一切。通常这时的建议严重偏向闭源和专有软件，但事实上并不用这样。

这是我挑选出的 19 个新的（或者对你而言新的）开源工具中的第 12 个工具来帮助你在 2019 年更有效率。

LogicalDOC

高效部分表现在能够在你需要时找到你所需的东西。我们都看到过塞满名称类似的文件的目录，这是每次更改文档时为了跟踪所有版本而重命名这些文件而导致的。例如，我的妻子是一名作家，她在将文档发送给审稿人之前，她经常使用新名称保存文档修订版。

程序员对此一个自然的解决方案是 Git 或者其他版本控制器，但这个不适用于文档作者，因为用于代码的系统通常不能很好地兼容商业文本编辑器使用的格式。之前有人说，“改变格式就行”，这不是适合每个人的选择。同样，许多版本控制工具对于非技术人员来说并不是非常友好。在大型组织中，有一些工具可以解决此问题，但它们还需要大型组织的资源来运行、管理和支持它们。

LogicalDOC CE 是为解决此问题而编写的开源文档管理系统。它允许用户签入、签出、查看版本、搜索和锁定文档，并保留版本历史记录，类似于程序员使用的版本控制工具。

LogicalDOC 可在 Linux、MacOS 和 Windows 上安装，使用基于 Java 的安装程序。在安装时，系统将提示你提供数据库存储位置，并提供只在本地文件存储的选项。你将获得访问服务器的 URL 和默认用户名和密码，以及保存用于自动安装脚本选项。

登录后，LogicalDOC 的默认页面会列出你已标记、签出的文档以及有关它们的最新说明。切换到“文档”选项卡将显示你有权访问的文件。你可以在界面中选择文件或使用拖放来上传文档。如果你上传 ZIP 文件，LogicalDOC 会解压它，并将其中的文件添加到仓库中。

右键单击文件将显示一个菜单选项，包括检出文件、锁定文件以防止更改，以及执行大量其他操作。签出文件会将其下载到本地计算机以便编辑。在重新签入之前，其他任何人都无法修改签出的文件。当重新签入文件时（使用相同的菜单），用户可以向版本添加标签，并且需要备注对其执行的操作。

查看早期版本只需在“版本”页面下载就行。对于某些第三方服务，它还有导入和导出选项，内置 Dropbox 支持。

文档管理不仅仅是能够负担得起昂贵解决方案的大公司才能有的。LogicalDOC 可帮助你追踪文档的版本历史，并为难以管理的文档提供了安全的仓库。

via: https://opensource.com/article/19/1/productivity-tool-logicaldoc

作者：Kevin Sonney 选题：lujun9972 译者：geekpi 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

手册页（man）是由系统管理员和 IT 技术开发人员写的，更多的是为了作为参考而不是教你如何使用。手册页对于已经熟悉使用 Linux、Unix 和 BSD 操作系统的人来说是非常有用的。如果你仅仅需要知道某个命令或者某个配置文件的格式那么你可以使用手册页，但是手册页对于 Linux 新手来说并没有太大的帮助。想要通过使用手册页来学习一些新东西不是一个好的选择。这里有将提供 30 个学习 Linux 和 Unix 操作系统的最佳在线网页文档。

值得一提的是，相对于 Linux，BSD 的手册页更好。

1：Red Hat Enterprise Linux（RHEL）

RHEL 是由红帽公司开发的面向商业市场的 Linux 发行版。红帽的文档是最好的文档之一，涵盖从 RHEL 的基础到一些高级主题比如安全、SELinux、虚拟化、目录服务器、服务器集群、JBOSS 应用程序服务器、高性能计算（HPC）等。红帽的文档已经被翻译成 22 种语言，发布成多页面 HTML、单页面 HTML、PDF、EPUB 等文件格式。好消息同样的文档你可以用于 Centos 和 Scientific Linux（社区企业发行版）。这些文档随操作系统一起下载提供，也就是说当你没有网络的时候，你也可以使用它们。RHEL 的文档涵盖从安装到配置器群的所有内容。唯一的缺点是你需要成为付费用户。当然这对于企业公司来说是一件完美的事。

1. RHEL 文档：HTML/PDF格式（LCTT 译注：此链接需要付费用户才可以访问）
2. 是否支持论坛：只能通过红帽公司的用户网站提交支持案例。

关于 CentOS Wiki 和论坛的说明

CentOS（ 社区企业操作系统 Community ENTerprise Operating System ）是由 RHEL 提供的自由源码包免费重建的。它为个人电脑或其它用途提供了可靠的、免费的企业级 Linux。你可以不用付出任何支持和认证费用就可以获得 RHEL 的稳定性。CentOS的 wiki 分为 Howto、技巧等等部分，链接如下：

1. 文档：wiki 格式
2. 是否支持论坛：是

2：Arch 的 Wiki 和论坛

Arch linux 是一个独立开发的 Linux 操作系统，它有基于 wiki 网站形式的非常不错的文档。它是由 Arch 社区的一些用户共同协作开发出来的，并且允许任何用户添加或修改内容。这些文档教程被分为几类比如说优化、软件包管理、系统管理、X window 系统还有获取安装 Arch Linux 等。它的官方论坛在解决许多问题的时候也非常有用。它有总共 4 万多个注册用户、超过 1 百万个帖子。 该 wiki 包含一些 其它 Linux 发行版也适用的通用信息。

1. Arch 社区文档：Wiki 格式
2. 是否支持论坛：是

3：Gentoo Linux Wiki 和论坛

Gentoo Linux 基于 Portage 包管理系统。Gentoo Linux 用户根据它们选择的配置在本地编译源代码。多数 Gentoo Linux 用户都会定制自己独有的程序集。 Gentoo Linux 的文档会给你一些有关 Gentoo Linux 操作系统的说明和一些有关安装、软件包、网络和其它等主要出现的问题的解决方法。Gentoo 有对你来说 非常有用的论坛，论坛中有超过 13 万 4 千的用户，总共发了有 5442416 个文章。

1. Gentoo 社区文档：手册 和 Wiki 格式
2. 是否支持论坛：是

4：Ubuntu Wiki 和文档

Ubuntu 是领先的台式机和笔记本电脑发行版之一。其官方文档由 Ubuntu 文档工程开发维护。你可以在从官方文档中查看大量的信息，比如如何开始使用 Ubuntu 的教程。最好的是，此处包含的这些信息也可用于基于 Debian 的其它系统。你可能会找到由 Ubuntu 的用户们创建的社区文档，这是一份有关 Ubuntu 的使用教程和技巧等。Ubuntu Linux 有着网络上最大的 Linux 社区的操作系统，它对新用户和有经验的用户均有助益。

1. Ubuntu 社区文档：wiki 格式
2. Ubuntu 官方文档：wiki 格式
3. 是否支持论坛：是

5：IBM Developer Works

IBM Developer Works 为 Linux 程序员和系统管理员提供技术资源，其中包含数以百计的文章、教程和技巧来协助 Linux 程序员的编程工作和应用开发还有系统管理员的日常工作。

1. IBM 开发者项目文档：HTML 格式
2. 是否支持论坛：是

6：FreeBSD 文档和手册

FreeBSD 的手册是由 FreeBSD 文档项目 FreeBSD Documentation Project 所创建的，它介绍了 FreeBSD 操作系统的安装、管理和一些日常使用技巧等内容。FreeBSD 的手册页通常比 GNU Linux 的手册页要好一点。FreeBSD 附带有全部最新手册页的文档。 FreeBSD 手册涵盖任何你想要的内容。手册包含一些通用的 Unix 资料，这些资料同样适用于其它的 Linux 发行版。FreeBSD 官方论坛会在你遇到棘手问题时给予帮助。

1. FreeBSD 文档：HTML/PDF 格式
2. 是否支持论坛：是

7：Bash Hackers Wiki

这是一个对于 bash 使用者来说非常好的资源。Bash 使用者的 wiki 是为了归纳所有类型的 GNU Bash 文档。这个项目的动力是为了提供可阅读的文档和资料来避免用户被迫一点一点阅读 Bash 的手册，有时候这是非常麻烦的。Bash Hackers Wiki 分为各个类，比如说脚本和通用资料、如何使用、代码风格、bash 命令格式和其它。

1. Bash 用户教程：wiki 格式

8：Bash 常见问题

这是一个为 bash 新手设计的一个 wiki。它收集了 IRC 网络的 #bash 频道里常见问题的解决方法，这些解决方法是由该频道的普通成员提供。当你遇到问题的时候不要忘了在 BashPitfalls 部分检索查找答案。这些常见问题的解决方法可能会倾向于 Bash，或者偏向于最基本的 Bourne Shell，这决定于是谁给出的答案。大多数情况会尽力提供可移植的（Bourne）和高效的（Bash，在适当情况下）的两类答案。

1. Bash 常见问题：wiki 格式

9: Howtoforge - Linux 教程

博客作者 Falko 在 Howtoforge 上有一些非常不错的东西。这个网站提供了 Linux 关于各种各样主题的教程，比如说其著名的“最佳服务器系列”，网站将主题分为几类，比如说 web 服务器、linux 发行版、DNS 服务器、虚拟化、高可用性、电子邮件和反垃圾邮件、FTP 服务器、编程主题还有一些其它的内容。这个网站也支持德语。

1. Howtoforge： html 格式
2. 是否支持论坛：是

10：OpenBSD 常见问题和文档

OpenBSD 是另一个基于 BSD 的类 Unix 计算机操作系统。OpenBSD 是由 NetBSD 项目分支而来。OpenBSD 因高质量的代码和文档、对软件许可协议的坚定立场和强烈关注安全问题而闻名。OpenBSD 的文档分为多个主题类别，比如说安装、包管理、防火墙设置、用户管理、网络、磁盘和磁盘阵列管理等。

1. OpenBSD：html 格式
2. 是否支持论坛：否，但是可以通过 邮件列表 来咨询

11: Calomel - 开源研究和参考文档

这个极好的网站是专门作为开源软件和那些特别专注于 OpenBSD 的软件的文档来使用的。这是最简洁的引导网站之一，专注于高质量的内容。网站内容分为多个类，比如说 DNS、OpenBSD、安全、web 服务器、Samba 文件服务器、各种工具等。

1. Calomel 官网：html 格式
2. 是否支持论坛：否

12：Slackware 书籍项目

Slackware Linux 是我的第一个 Linux 发行版。Slackware 是基于 Linux 内核的最早的发行版之一，也是当前正在维护的最古老的 Linux 发行版。 这个发行版面向专注于稳定性的高级用户。 Slackware 也是很少有的的“类 Unix” 的 Linux 发行版之一。官方的 Slackware 手册是为了让用户快速开始了解 Slackware 操作系统的使用方法而设计的。 这不是说它将包含发行版的每一个方面，而是为了说明它的实用性和给使用者一些有关系统的基础工作使用方法。手册分为多个主题，比如说安装、网络和系统配置、系统管理、包管理等。

1. Slackware Linux 手册：html 格式、pdf 和其它格式
2. 是否支持论坛：是

13：Linux 文档项目（TLDP）

Linux 文档项目 Linux Documentation Project 旨在给 Linux 操作系统提供自由、高质量文档。网站是由志愿者创建和维护的。网站分为具体主题的帮助、由浅入深的指南等。在此我想推荐一个非常好的文档，这个文档既是一个教程也是一个 shell 脚本编程的参考文档，对于新用户来说这个 HOWTO 的列表也是一个不错的开始。

1. Linux 文档工程 支持多种查阅格式
2. 是否支持论坛：否

14：Linux Home Networking

Linux Home Networking 是学习 linux 的另一个比较好的资源，这个网站包含了 Linux 软件认证考试的内容比如 RHCE，还有一些计算机培训课程。网站包含了许多主题，比如说网络、Samba 文件服务器、无线网络、web 服务器等。

1. Linux home networking 可通过 html 格式和 PDF（少量费用）格式查阅
2. 是否支持论坛：是

15：Linux Action Show

Linux Action Show（LAS) 是一个关于 Linux 的播客。这个网站是由 Bryan Lunduke、Allan Jude 和 Chris Fisher 共同管理的。它包含了 FOSS 的最新消息。网站内容主要是评论一些应用程序和 Linux 发行版。有时候也会发布一些和开源项目著名人物的采访视频。

1. Linux action show 支持音频和视频格式
2. 是否支持论坛：是

16：Commandlinefu

Commandlinefu 列出了各种有用或有趣的 shell 命令。这里所有命令都可以评论、讨论和投票（支持或反对）。对于所有 Unix 命令行用户来说是一个极好的资源。不要忘了查看评选出来的最佳命令。

1. Commandlinefu 支持 html 格式
2. 是否支持论坛：否

17：Debian 管理技巧和资源

这个网站包含一些只和 Debian GNU/Linux 相关的主题、技巧和教程，特别是包含了关于系统管理的有趣和有用的信息。你可以在上面贡献文章、建议和问题。提交了之后不要忘记查看最佳文章列表里有没有你的文章。

1. Debian 系统管理 支持 html 格式
2. 是否支持论坛：否

18: Catonmat - Sed、Awk、Perl 教程

这个网站是由博客作者 Peteris Krumins 维护的。主要关注命令行和 Unix 编程主题，比如说 sed 流编辑器、perl 语言、AWK 文本处理工具等。不要忘了查看 sed 介绍、sed 含义解释，还有命令行历史的权威介绍。

1. catonmat 支持 html 格式
2. 是否支持论坛：否

19：Debian GNU/Linux 文档和 Wiki

Debian 是另外一个 Linux 操作系统，其主要使用的软件以 GNU 许可证发布。Debian 因严格坚持 Unix 和自由软件的理念而闻名，它也是很受欢迎并且有一定影响力的 Linux 发行版本之一。 Ubuntu 等发行版本都是基于 Debian 的。Debian 项目以一种易于访问的形式提供给用户合适的文档。这个网站分为 Wiki、安装指导、常见问题、支持论坛几个模块。

1. Debian GNU/Linux 文档 支持 html 和其它格式访问
2. Debian GNU/Linux wiki
3. 是否支持论坛：是

20：Linux Sea

Linux Sea 这本书提供了比较通俗易懂但充满技术（从最终用户角度来看）的 Linux 操作系统的介绍，使用 Gentoo Linux 作为例子。它既没有谈论 Linux 内核或 Linux 发行版的历史，也没有谈到 Linux 用户不那么感兴趣的细节。

1. Linux sea 支持 html 格式访问
2. 是否支持论坛: 否

21：O'reilly Commons

O'reilly 出版社发布了不少 wiki 格式的文章。这个网站主要是为了给那些喜欢创作、参考、使用、修改、更新和修订来自 O'Reilly 或者其它来源的素材的社区提供资料。这个网站包含关于 Ubuntu、PHP、Spamassassin、Linux 等的免费书籍。

1. Oreilly commons 支持 Wiki 格式
2. 是否支持论坛：否

22：Ubuntu 袖珍指南

这本书的作者是 Keir Thomas。这本指南（或者说是书籍）对于所有 ubuntu 用户来说都值得一读。这本书旨在向用户介绍 Ubuntu 操作系统和其所依赖的理念。你可以从官网下载这本书的 PDF 版本，也可以在亚马逊买印刷版。

1. Ubuntu pocket guide 支持 PDF 和印刷版本.
2. 是否支持论坛：否

23: Linux: Rute User’s Tutorial and Exposition

这本书涵盖了 GNU/LINUX 系统管理，主要是对主流的发布版本比如红帽和 Debian 的说明，可以作为新用户的教程和高级管理员的参考。这本书旨在给出 Unix 系统的每个面的简明彻底的解释和实践性的例子。想要全面了解 Linux 的人都不需要再看了 —— 这里没有涉及的内容。

1. Linux: Rute User’s Tutorial and Exposition 支持印刷版和 html 格式
2. 是否支持论坛：否

24：高级 Linux 编程

这本书是写给那些已经熟悉了 C 语言编程的程序员的。这本书采取一种教程式的方式来讲述大多数在 GNU/Linux 系统应用编程中重要的概念和功能特性。如果你是一个已经对 GNU/Linux 系统编程有一定经验的开发者，或者是对其它类 Unix 系统编程有一定经验的开发者，或者对 GNU/Linux 软件开发有兴趣，或者想要从非 Unix 系统环境转换到 Unix 平台并且已经熟悉了优秀软件的开发原则，那你很适合读这本书。另外，你会发现这本书同样适合于 C 和 C++ 编程。

1. 高级 Linux 编程 支持印刷版和 PDF 格式
2. 是否支持论坛：否

25: LPI 101 Course Notes

LPIC 1、2、3 级是用于 Linux 系统管理员认证的。这个网站提供了 LPI 101 和 LPI 102 的测试训练。这些是根据 GNU 自由文档协议 GNU Free Documentation Licence （FDL）发布的。这些课程材料基于 Linux 国际专业协会的 LPI 101 和 102 考试的目标。这个课程是为了提供给你一些必备的 Linux 系统的操作和管理的技能。

1. LPI 训练手册 支持 PDF 格式
2. 是否支持论坛：否

26: FLOSS 手册

FLOSS 手册是一系列关于自由和开源软件以及用于创建它们的工具和使用这些工具的社区的手册。社区的成员包含作者、编辑、设计师、软件开发者、积极分子等。这些手册中说明了怎样安装使用一些自由和开源软件，如何操作（比如设计和维持在线安全）开源软件，这其中也包含如何使用或支持自由软件和格式的自由文化服务手册。你也会发现关于一些像 VLC、 Linux 视频编辑、 Linux、 OLPC / SUGAR、 GRAPHICS 等软件的手册。

1. 你可以浏览 FOSS 手册 支持 Wiki 格式
2. 是否支持论坛：否

27：Linux 入门包

刚接触 Linux 这个美好世界？想找一个简单的入门方式？你可以下载一个 130 页的指南来入门。这个指南会向你展示如何在你的个人电脑上安装 Linux，如何浏览桌面，掌握最主流行的 Linux 程序和修复可能出现的问题的方法。

1. Linux 入门包支持 PDF 格式
2. 是否支持论坛：否

28：Linux.com - Linux 信息来源

Linux.com 是 Linux 基金会的一个产品。这个网站上提供一些新闻、指南、教程和一些关于 Linux 的其它信息。利用全球 Linux 用户的力量来通知、写作、连接 Linux 的事务。

1. 在线访问 Linux.com
2. 是否支持论坛：是

29: LWN

LWN 是一个注重自由软件及用于 Linux 和其它类 Unix 操作系统的软件的网站。这个网站有周刊、基本上每天发布的单独文章和文章的讨论对话。该网站提供有关 Linux 和 FOSS 相关的开发、法律、商业和安全问题的全面报道。

1. 在线访问 lwn.net
2. 是否支持论坛：否

30：Mac OS X 相关网站

与 Mac OS X 相关网站的快速链接：

• Mac OS X 提示 —— 这个网站专用于苹果的 Mac OS X Unix 操作系统。网站有很多有关 Bash 和 Mac OS X 的使用建议、技巧和教程
• Mac OS 开发库 —— 苹果拥有大量和 OS X 开发相关的优秀系列内容。不要忘了看一看 bash shell 脚本入门
• Apple 知识库 - 这个有点像 RHN 的知识库。这个网站提供了所有苹果产品包括 OS X 相关的指南和故障报修建议。

30: NetBSD

（LCTT 译注：没错，又一个 30）

NetBSD 是另一个基于 BSD Unix 操作系统的自由开源操作系统。NetBSD 项目专注于系统的高质量设计、稳定性和性能。由于 NetBSD 的可移植性和伯克利式的许可证，NetBSD 常用于嵌入式系统。这个网站提供了一些 NetBSD 官方文档和各种第三方文档的链接。

1. 在线访问 netbsd 文档，支持 html、PDF 格式
2. 是否支持论坛：否

你要做的事

这是我的个人列表，这可能并不完全是权威的，因此如果你有你自己喜欢的独特 Unix/Linux 网站，可以在下方参与评论分享。

// 图片来源: Flickr photo PanelSwitchman。一些连接是用户在我们的 Facebook 粉丝页面上建议添加的。

关于作者

作者是 nixCraft 的创建者和经验丰富的系统管理员以及 Linux 操作系统 / Unix shell 脚本的培训师。它曾与全球客户及各行各业合作，包括 IT、教育，国防和空间研究以及一些非营利部门。可以关注作者的 Twitter、Facebook、Google+。

via: https://www.cyberciti.biz/tips/linux-unix-bsd-documentations.html

作者：Vivek Gite 译者：ScarboroughCoral 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

帮助用户在智能手机或平板上快速轻松地找到他们所需的信息。

我并不是完全相信移动为先的理念，但是我确实发现更多的人使用智能手机和平板电脑等移动设备来获取信息。这包括在线的软件和硬件文档，但它们大部分都是冗长的，不适合小屏幕。通常情况下，它的伸缩性不太好，而且很难导航。

当用户使用移动设备访问文档时，他们通常需要迅速获取信息以了解如何执行任务或解决问题，他们不想通过看似无尽的页面来寻找他们需要的特定信息。幸运的是，解决这个问题并不难。以下是一些技巧，可以帮助你构建文档以满足移动阅读器的需求。

简短一点

这意味着简短的句子，简短的段落和简短的流程。你不是在写一部长篇小说或一段长新闻。使你的文档简洁。尽可能使用少量的语言来获得想法和信息。

以广播新闻报道为示范：关注关键要素，用简单直接的语言对其进行解释。不要让你的读者在屏幕上看到冗长的文字。

另外，直接切入重点。关注读者需要的信息。在线发布的文档不应该像以前厚厚的手册一样。不要把所有东西都放在一个页面上，把你的信息分成更小的块。接下来是怎样做到这一点：

主题

在技术写作的世界里，主题是独立的，独立的信息块。每个主题都由你网站上的单个页面组成。读者应该能从特定的主题中获取他们需要的信息 -- 并且只是那些信息。要做到这一点，选择哪些主题要包含在文档中并决定如何组织它们：

DITA

达尔文信息类型化体系结构 Darwin Information Typing Architecture （DITA） 是用于编写和发布的一个 XML 模型。它广泛采用在技术写作中，特别是作为较长的文档集中。

我并不是建议你将文档转换为 XML（除非你真的想）。相反，考虑将 DITA 的不同类型主题的概念应用到你的文档中：

• 一般：概述信息
• 任务：分步骤的流程
• 概念：背景或概念信息
• 参考：API 参考或数据字典等专用信息
• 术语表：定义术语
• 故障排除：有关用户可能遇到的问题以及如何解决问题的信息

你会得到很多单独的页面。要连接这些页面：

链接

许多内容管理系统、维基和发布框架都包含某种形式的导航 —— 通常是目录或面包屑导航)，这是一种在移动设备上逐渐消失的导航。

为了加强导航，在主题之间添加明确的链接。将这些链接放在每个主题末尾的“另请参阅”或“相关主题”的标题处。每个部分应包含两到五个链接，指向与当前主题相关的概述、概念和参考主题。

如果你需要指向文档集之外的信息，请确保链接在浏览器新的选项卡中打开。这将把读者送到另一个网站，同时也将读者继续留你的网站上。

这解决了文本问题，那么图片呢？

不使用图片

除少数情况之外，不应该加太多图片到文档中。仔细查看文档中的每个图片，然后问自己：

• 它有用吗？
• 它是否增强了文档？
• 如果删除它，读者会错过这张图片吗？

如果回答否，那么移除图片。

另一方面，如果你绝对不能没有图片，就让它变成响应式的。这样，图片就会自动调整以适应更小的屏幕。

如果你仍然不确定图片是否应该出现，Opensource.com 社区版主 Ben Cotton 提供了一个关于在文档中使用屏幕截图的极好的解释。

最后的想法

通过少量努力，你就可以构建适合移动设备用户的文档。此外，这些更改也改进了桌面计算机和笔记本电脑用户的文档体验。

via: https://opensource.com/article/17/12/think-mobile

作者：Scott Nesbitt 译者：MjSeven 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

让我们了解一下如何使国外读者更容易理解你的技术文章。

英语是开源社区的通用语言。为了减少翻译成本，很多团队都改成用英语来写他们的文档。 但奇怪的是，为国际读者写英语并不一定就意味着以英语为母语的人就占据更多的优势。 相反， 他们往往忘记了该文档用的语言可能并不是读者的母语。

我们以下面这个简单的句子为例： “Encrypt the password using the foo bar command。”语法上来说，这个句子是正确的。 鉴于动名词的 “-ing” 形式在英语中很常见，大多数的母语人士都认为这是一种优雅的表达方式， 他们通常会很自然的写出这样的句子。 但是仔细观察， 这个句子存在歧义因为 “using” 可能指的宾语（“the password”）也可能指的动词(“encrypt”）。 因此这个句子有两种解读方式:

• “加密使用了 foo bar 命令的密码。”
• “使用命令 foo bar 来加密密码。”

如果你有相关的先验知识（密码加密或者 foo bar 命令），你可以消除这种不确定性并且明白第二种方式才是真正的意思。 但是若你没有足够深入的知识怎么办呢？ 如果你并不是这方面的专家，而只是一个拥有泛泛相关知识的翻译者而已怎么办呢？ 再或者，如果你只是个非母语人士且对像动名词这种高级语法不熟悉怎么办呢？

即使是英语为母语的人也需要经过训练才能写出清晰直接的技术文档。训练的第一步就是提高对文本可用性以及潜在问题的警觉性， 下面让我们来看一下可以帮助避免常见陷阱的 7 条规则。

1、了解你的目标读者并代入其中。

如果你是一名开发者，而写作的对象是最终用户， 那么你需要站在他们的角度来看这个产品。 文档的结构是否反映了用户的目标？ 人格面具 persona 技术) 能帮你专注于目标受众并为你的读者提供合适层次的细节。

2、遵循 KISS 原则——保持文档简短而简单

这个原则适用于多个层次，从语法，句子到单词。 比如:

• 使用合适的最简单时态。比如， 当提到一个动作的结果时使用现在时:

  • " Click 'OK.' The 'Printer Options' dialog will appear. " -> "Click 'OK.' The 'Printer Options' dialog appears."
• 按经验来说，一个句子表达一个主题；然而， 短句子并不一定就容易理解（尤其当这些句子都是由名词组成时）。 有时， 将句子裁剪过度可能会引起歧义，而反过来太多单词则又难以理解。

• 不常用的以及很长的单词会降低阅读速度，而且可能成为非母语人士的障碍。 使用更简单的替代词语:

  • " utilize " -> "use"
  • " indicate " -> "show"，"tell" 或 "say"
  • " prerequisite " -> "requirement"

3、不要干扰阅读流

将虚词和较长的插入语移到句子的首部或者尾部:

• " They are not, however, marked as installed. " -> "However, they are not marked as installed."

将长命令放在句子的末尾可以让自动/半自动的翻译拥有更好的断句。

4、区别对待两种基本的信息类型

描述型信息以及任务导向型信息有必要区分开来。描述型信息的一个典型例子就是命令行参考， 而 HOWTO 则是属于基于任务的信息；（LCTT 译注：HOWTO 文档是 Linux 文档中的一种）然而， 技术写作中都会涉及这两种类型的信息。 仔细观察， 就会发现许多文本都同时包含了两种类型的信息。 然而如果能够清晰地划分这两种类型的信息那必是极好的。 为了更好地区分它们，可以对它们进行分别标记。 标题应该能够反映章节的内容以及信息的类型。 对描述性章节使用基于名词的标题（比如“Types of Frobnicators”），而对基于任务的章节使用口头表达式的标题（例如“Installing Frobnicators”）。 这可以让读者快速定位感兴趣的章节而跳过对他无用的章节。

5、考虑不同的阅读场景和阅读模式

有些读者在阅读产品文档时会由于自己搞不定而感到十分的沮丧。他们在一个嘈杂的环境中工作，也很难专注于阅读。 同时，不要期望你的读者会一页一页的进行阅读，很多人都是快速浏览文本，搜索关键字或者通过表格、索引以及全文搜索的方式来查找主题。 请牢记这一点， 从不同的角度来看待你的文字。 通常需要折中才能找到一种适合多种情况的文本结构。

6、将复杂的信息分成小块

这会让读者更容易记住和吸收信息。例如， 过程不应该超过 7 到 10 个步骤（根据认知心理学中的 米勒法则）。 如果需要更多的步骤， 那么就将任务分拆成不同的过程。

7、形式遵循功能

根据以下问题检查你的文字：某句话/段落/章节的 目的（功能）是什么？比如，它是一个指令呢？还是一个结果呢？还是一个警告呢？如果是指令， 使用主动语气： “Configure the system.” 被动语气可能适合于进行描述： “The system is configured automatically.” 将警告放在危险操作的 前面 。 专注于目的还有助于发现冗余的内容，可以清除类似 “basically” 或者 “easily” 这一类的填充词，类似 “already existing ” 或“ completely new” 这一类的不必要的修饰， 以及任何与你的目标大众无关的内容。

你现在可能已经猜到了，写作就是一个不断重写的过程。 好的写作需要付出努力和练习。 即使你只是偶尔写点东西， 你也可以通过关注目标大众并遵循上述规则来显著地改善你的文字。 文字的可读性越好， 理解就越容易， 这一点对不同语言能力的读者来说都是适合的。 尤其是当进行本地化时， 高质量的原始文本至关重要：“垃圾进， 垃圾出”。 如果原始文本就有缺陷， 翻译所需要的时间就会变长， 从而导致更高的成本。 最坏的情况下， 翻译会导致缺陷成倍增加，需要在不同的语言版本中修正这个缺陷。

via: https://opensource.com/article/17/12/7-rules

作者：Tanja Roth 译者：lujun9972 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

通过卡片分类和看板来给用户提供他们想要的信息。

如果你正在处理文档、网站或其他面向用户的内容，那么了解用户希望找到的内容（包括他们想要的信息以及信息的组织和结构）很有帮助。毕竟，如果人们无法找到他们想要的东西，那么再出色的内容也没有用。

卡片分类是一种简单而有效的方式，可以从用户那里收集有关菜单界面和页面的内容。最简单的实现方式是在计划在网站或文档中的部分分类标注一些索引卡，并要求用户按照查找信息的方式对卡片进行分类。一个变体是让人们编写自己的菜单标题或内容元素。

我们的目标是了解用户的期望以及他们希望在哪里找到它，而不是自己弄清楚菜单和布局。当与用户处于相同的物理位置时，这是相对简单的，但当尝试从多个位置的人员获得反馈时，这会更具挑战性。

我发现 看板 kanban 对于这些情况是一个很好的工具。它允许人们轻松拖动虚拟卡片进行分类和排名，而且与专门卡片分类软件不同，它们是多用途的。

我经常使用 Trello 进行卡片分类，但有几种你可能想尝试的开源替代品。

怎么运行的

我最成功的看板体验是在写 Gluster 文档的时候 —— 这是一个自由开源的可扩展的网络存储文件系统。我需要携带大量随着时间而增长的文档，并将其分成若干类别以创建导航系统。由于我没有必要的技术知识来分类，我向 Gluster 团队和开发人员社区寻求指导。

首先，我创建了一个共享看板。我列出了一些通用名称，这些名称可以为我计划在文档中涵盖的所有主题排序和创建卡片。我标记了一些不同颜色的卡片，以表明某个主题缺失并需要创建，或者它存在并需要删除。然后，我把所有卡片放入“未排序”一列，并要求人们将它们拖到他们认为这些卡片应该组织到的地方，然后给我一个他们认为是理想状态的截图。

处理所有截图是最棘手的部分。我希望有一个合并或共识功能可以帮助我汇总每个人的数据，而不必检查一堆截图。幸运的是，在第一个人对卡片进行分类之后，人们或多或少地对该结构达成一致，而只做了很小的修改。当对某个主题的位置有不同意见时，我发起一个快速会议，让人们可以解释他们的想法，并且可以排除分歧。

使用数据

在这里，很容易将捕捉到的信息转换为菜单并对其进行优化。如果用户认为项目应该成为子菜单，他们通常会在评论中或在电话聊天时告诉我。对菜单组织的看法因人们的工作任务而异，所以从来没有完全达成一致意见，但用户进行测试意味着你不会对人们使用什么以及在哪里查找有很多盲点。

将卡片分类与分析功能配对，可以让你更深入地了解人们在寻找什么。有一次，当我对一些我正在写的培训文档进行分析时，我惊讶地发现搜索量最大的页面是关于资本的。所以我在顶层菜单层面上显示了该页面，即使我的“逻辑”设置将它放在了子菜单中。

我发现看板卡片分类是一种很好的方式，可以帮助我创建用户想要查看的内容，并将其放在希望被找到的位置。你是否发现了另一种对用户友好的组织内容的方法？或者看板的另一种有趣用途是什么？如果有的话，请在评论中分享你的想法。

via: https://opensource.com/article/17/11/kanban-boards-card-sorting

作者：Heidi Waterhouse 译者：geekpi 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出