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