本文最早于2017.10.24發(fā)布于 TC互聯(lián)技術傳播社區(qū)，時任互聯(lián)小編。內容未有更新，僅遷移備份至個人賬號。
最近正在學習DITA標準的結構化文檔寫作，在練習這種新型寫作理念時發(fā)現(xiàn)，DITA各元素中最靈活但也最具挑戰(zhàn)性的元素可能就是<shortdesc>，因為它能做的比僅僅充當一個主題的第一段還要多。簡短描述（short description）文本會出現(xiàn)在鏈接中，在某些情況下也回出現(xiàn)在搜索引擎結果中。
因此，當把內容轉換為DITA或者開始創(chuàng)作首個DITA主題時，創(chuàng)作有效的簡短描述成為重中之重。
那么，今天就來一起聊聊如何寫好簡短描述（short description）。
簡短描述在文中的位置
簡短描述，元素標簽<shortdesc>，是一個topic的第一個段落，其有效位置有：
- concept、task和reference主題的<title>元素和topic body之間。
- <abstract>元素內，位置也位于<title>元素和body主體之間。
- DITA map文件中的<topicref>元素內。
簡短描述在文中的作用
簡短描述常有以下幾種用途：
- 一個topic的第一個段落
- 相關鏈接或子topic鏈接的鏈接預覽（相關鏈接的懸停文本或者子主題鏈接下方的文本）
- 作為搜索引擎搜索結果的摘要
如何寫好簡短描述
如何簡潔、高效寫好簡短描述？簡短描述應該要描述整個主題的目的和中心點，通常可以關注兩個問題：
- 該主題是關于什么的？
- 為什么用戶需要關注該主題，或者用戶需要從中獲得什么信息？
Tips：
請在每個topic中都包含short description，且保持連續(xù)、一致。
為確保所有主題都包含short description，建議將<shortdesc>的屬性規(guī)定成required，并且增加發(fā)布規(guī)則，在該元素缺失時提醒錯誤。
確保簡短描述使用的是完整的句子，語法正確，標點恰當，并且符合風格指南。
不要在簡短描述中引入列表、圖片或者表格。
請確保簡短描述的簡潔性！一般字數(shù)控制在35字以內，極少數(shù)情況下，50字為上限。
若簡短描述太長，請考慮將部分信息轉移至body中呈現(xiàn)。
-
避免“自解釋”式的簡短描述，徒增無效字數(shù)而無有效信息。避免諸如以下的句式：
- this topic describes....
- this concept covers....
- this information is about....
- the following chapter explains...
簡短描述不要簡單的重復topic title！
不要在簡短描述中使用交叉引用<xref>元素！
說了這么多，辣么，在不同主題中，究竟該如何開始簡短描述的寫作呢？下面，就一起來看看有沒有什么具體的技巧。
Task topic中的簡短描述
task topic的簡短描述寫作指導?？苫卮鹨韵乱粋€或多個問題：
- 該task能幫助用戶完成什么？
- 進行此項task的好處是什么？或者為什么task重要？
- 用戶在何時該執(zhí)行task？
- 執(zhí)行task需要用到什么？
- 為什么用戶需要完成task？
- task是如何與其他相關task聯(lián)系的？
請記得：
- 關注task的益處或重要性
- 提供task步驟的概覽
- 關注實際目標，而不是產(chǎn)品功能
- 提供簡短的概念性信息
- 說明各個task是如何關聯(lián)的
Concept topic中的簡短描述
concept topic簡短描述寫作指導：
- 對象、概念是什么？
- 為什么用戶需要關心這一對象、概念？
請記得：
- 簡要給對象或概念下定義
- 解釋為什么用戶需要理解這一概念
Reference topic中的簡短描述
reference topic 簡短描述寫作指導：
- 這一對象是做什么的？
- 這一對象是如何工作的？
- 這一對象用于什么或者為什么它有用？
請記得：
- 給對象下定義或者解釋該對象是用于做什么
- 說明用戶為什么使用這一對象
