今天不继续写topic，插一篇，说说如何写好短描述。看着标题特别像卖十全大补丸的，哈哈。不过《DITA最佳实践》一书甚是有趣，每天翻三五页，so easy。记录下来，供大家一乐。
今天看的是短描述，这个内容被放在三大topic之后来讲，可见其重要性，也可见将其写好难度之大。
写好短描述要点
1.简要介绍topic的内容，让读者通过链接或者预览时，能够清楚知道是不是自己需要的内容。这是老话，就不重提了。
2.每一个topic都要有短描述。这也就是所谓的标题和主体内容之间的过渡和连接。话说我曾经见过自己的手册从1.简介到1.1概述到1.1.1参数列表(纯属举例，不针对任何人)，到表1-1参数列表，中间没有任何的过渡。
要保持一致，给每个topic加短描述，不要有遗漏，否则会让读者误以为是作者忘记了或者显示不全。
3.使用语法完整的句子，而非短语。
当然，此条并非强制要求，强烈建议而已。完整的句子更易于理解，利于检索。
4.不要使用短描述引导后续的表格，图片，列表。简言之，短描述必须是完整的句子，不能以冒号，逗号结尾。
否则，在短描述以超链接形式显示时非常怪异。“本系统拥有如下优异性能:”，就完了。就好像被卡着脖子，剩下的一半没有表达。
5.短描述，顾名思义，要尽量短，用英文避免超过50字符，尽量不超过35字符。其实也就是一个长句或者两个短句的体量。
6.避免以自我为中心，比如“本文讲述了”，“本章节概述了”，“如下内容将要”，都术语废话，浪费35个词的限额。因为这些话都属于没有任何意义的话语。但是我发现，如果不好好动脑子，就经常会不由自主写出类似的描述。因为不过脑子，套八股。
7.避免使用交叉链接
这个容易理解，想想一下你悬浮鼠标，查看某个超链接网页的概述，想要看看是不是感兴趣的内容。却发现悬浮的tips中竟然还带着参引某处的超链接，“欲知详情，且看xx分解”，该是多么崩溃的事情。
8..对于任务类topic，短描述要说明此任务的重要性和可能带来的收益。什么情况下需要执行?与其他任务的相关性，等等。
类似“1.系统配置 此章节概述系统配置的配置步骤”这样的短描述，读者看到后，内心肯定是拒绝的。因为从标题就能知道这是要做什么，不需要重复。但是用户如果没看到明显受益，就不知道自己为什么要做，也失去了继续阅读的兴趣。聚焦真实的操作，而非系统功能。
简要概述本task的操作步骤，比如“通过工具箱，控制面板，进行xx设置”。对于熟练用户，可能已经足够完成任务了，都不用再细看topic的内容。
把此项任务与其它项关联起来。比如，“开始驾驶前，需要调节好座椅，后视镜，系好安全带"。但是，一定不要出现类似“xx内容将在下一节展开描述”，或者“如前面章节所属，xx”，这会让复用变得相对困难。
9.概念性topic
短描述要介绍本topic的核心概念，所以必须是中心句。不能整个短描述都结束了，还在为核心概念做铺垫，半抱琵琶犹遮面。
要为用户说明为什么需理解这个概念，不能用这样的词“xx概念非常重要”，或者“xx操作可以带来很多收益”，都是废话。
10.参考性topic
还是那句话，要给用户一个读下去的理由，比如本topic介绍的主体主要做什么用途，这个物体工作原理是什么，这个主体主要用于什么场合，等等。
最后的最后，结构化迁移注意事项:千万别为了偷懒，默认使用第一个段落作为数据迁移之后的短描述。否则，虽然节省时间，但数据质量严重受影响。因为，对用户来说，最关键的内容就是短描述，用户如果在几秒内已经发现topic不知所云，硬着头皮读下去可能性不高。就像第一口就知道这个鸡蛋不好吃，肯定就不会再继续品尝下去。
好了，本文虽然是讲短描述，可是长度已经破了历史记录，就此打住。
网友评论