本文最早于2017.10.24发布于 TC互联技术传播社区，时任互联小编。内容未有更新，仅迁移备份至个人账号。
最近正在学习DITA标准的结构化文档写作，在练习这种新型写作理念时发现，DITA各元素中最灵活但也最具挑战性的元素可能就是<shortdesc>，因为它能做的比仅仅充当一个主题的第一段还要多。简短描述（short description）文本会出现在链接中，在某些情况下也回出现在搜索引擎结果中。
因此，当把内容转换为DITA或者开始创作首个DITA主题时，创作有效的简短描述成为重中之重。
那么，今天就来一起聊聊如何写好简短描述（short description）。
简短描述在文中的位置
简短描述，元素标签<shortdesc>，是一个topic的第一个段落，其有效位置有：
- concept、task和reference主题的<title>元素和topic body之间。
- <abstract>元素内，位置也位于<title>元素和body主体之间。
- DITA map文件中的<topicref>元素内。
简短描述在文中的作用
简短描述常有以下几种用途：
- 一个topic的第一个段落
- 相关链接或子topic链接的链接预览（相关链接的悬停文本或者子主题链接下方的文本）
- 作为搜索引擎搜索结果的摘要
如何写好简短描述
如何简洁、高效写好简短描述？简短描述应该要描述整个主题的目的和中心点，通常可以关注两个问题：
- 该主题是关于什么的？
- 为什么用户需要关注该主题，或者用户需要从中获得什么信息？
Tips：
请在每个topic中都包含short description，且保持连续、一致。
为确保所有主题都包含short description，建议将<shortdesc>的属性规定成required，并且增加发布规则，在该元素缺失时提醒错误。
确保简短描述使用的是完整的句子，语法正确，标点恰当，并且符合风格指南。
不要在简短描述中引入列表、图片或者表格。
请确保简短描述的简洁性！一般字数控制在35字以内，极少数情况下，50字为上限。
若简短描述太长，请考虑将部分信息转移至body中呈现。
-
避免“自解释”式的简短描述，徒增无效字数而无有效信息。避免诸如以下的句式：
- this topic describes....
- this concept covers....
- this information is about....
- the following chapter explains...
简短描述不要简单的重复topic title！
不要在简短描述中使用交叉引用<xref>元素！
说了这么多，辣么，在不同主题中，究竟该如何开始简短描述的写作呢？下面，就一起来看看有没有什么具体的技巧。
Task topic中的简短描述
task topic的简短描述写作指导。可回答以下一个或多个问题：
- 该task能帮助用户完成什么？
- 进行此项task的好处是什么？或者为什么task重要？
- 用户在何时该执行task？
- 执行task需要用到什么？
- 为什么用户需要完成task？
- task是如何与其他相关task联系的？
请记得：
- 关注task的益处或重要性
- 提供task步骤的概览
- 关注实际目标，而不是产品功能
- 提供简短的概念性信息
- 说明各个task是如何关联的
Concept topic中的简短描述
concept topic简短描述写作指导：
- 对象、概念是什么？
- 为什么用户需要关心这一对象、概念？
请记得：
- 简要给对象或概念下定义
- 解释为什么用户需要理解这一概念
Reference topic中的简短描述
reference topic 简短描述写作指导：
- 这一对象是做什么的？
- 这一对象是如何工作的？
- 这一对象用于什么或者为什么它有用？
请记得：
- 给对象下定义或者解释该对象是用于做什么
- 说明用户为什么使用这一对象
