从高山阵屋看可获取性在技术文档中的重要性

笔者今年年初游览了日本名古屋附近的几个景点,其中尤以高山阵屋印象深刻。但凡参观过日本各种本丸御殿和天守阁的同学都会注意到,此类景点都会清楚的标明参观路线。殿中每隔一段距离就会在合适的地方标记“顺路”“归路”或者“上行”“下行”。因此,各个景点虽然游客不少,但都是井然有序。

1
犬山城和高山阵屋
下图是在“日本四大国宝城”之一的犬山城。上楼和下楼标识的清清楚楚,游客按照标识走,就会井然有序。
下图为位于高山县的高山阵屋。据说在幕府末期全国各地曾经存留的60多处郡代、代官衙门中,唯一一处保存有当时建筑的仅有高山阵屋。是全国唯一仅存的遗迹。
这个阵屋既是官员受理行政事务的地方,也是他们及家属居住的场所,还要用作囤积粮食的仓库。因此阵屋里的布局相比本丸御殿要复杂的多。整个阵屋根据功能被分割成很多个小房间。夸张来说,是有些像个简单的迷宫了。因此要想顺利参观完这个阵屋而不走回头路,貌似不是件容易的事。
来看看他们是怎么标识的。
为了不走回头路,他们是这样标识的。
是不是很有意思?
2
技术文档中的可获取性
这种类似的指引在技术文档中被称为可获取性(Retrievability),指快速找到需要的内容。
下面让我们来温习下DQTI(Developing Quality Technical Information)是怎么来阐述可获取性的。
DQTI认为,高质量文档有9个特征(笔者根据自己的理解翻译如下):
高质量文档的九个特征
【易用】
基于任务
内容正确
信息完整
【易懂】
文字清晰
内容具体
风格统一
【易找】
结构合理
易于获取
视觉效果
在结构合理的基础上,如果能帮助用户更加方便的找到他想查看的内容,技术文档就会获得更佳的用户体验。
文档中的各种入口和路标,都是能够帮助用户查找内容的元素。
可获取性的常见例子:
目录 | Table of Contents
索引 | Index
对照 | Cross-references
链接 | Links
标题 | Headings
高亮 | Highlighting
图标 | Icons
下图就是一个可获取性在技术文档中的实例。大家可以看到红框标注的都是可获取性元素。
正是因为这些元素的帮助,读者才能更加便利的找到他们想要的内容。
在了解到可获取性在技术文档中的作用后,笔者相信各位在阅读或者撰写技术文档的时候,可以做个有心人,找找哪些是可获取性元素。同时可以充分的利用可获取性元素,来增加文章的可读性。
 
 

0 条评论 次浏览

留下评论/回复