本文最早于2017.10.24發(fā)布于 TC互聯(lián)技術(shù)傳播社區(qū)舞竿，時(shí)任互聯(lián)小編搀捷。內(nèi)容未有更新锅很，僅遷移備份至個(gè)人賬號(hào)其馏。
最近正在學(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)，通臣埠辏可以關(guān)注兩個(gè)問題：
- 該主題是關(guān)于什么的张足？
- 為什么用戶需要關(guān)注該主題，或者用戶需要從中獲得什么信息坎藐？
Tips：
請(qǐng)?jiān)诿總€(gè)topic中都包含short description为牍，且保持連續(xù)、一致岩馍。
為確保所有主題都包含short description碉咆，建議將<shortdesc>的屬性規(guī)定成required，并且增加發(fā)布規(guī)則蛀恩，在該元素缺失時(shí)提醒錯(cuò)誤疫铜。
確保簡短描述使用的是完整的句子，語法正確双谆，標(biāo)點(diǎn)恰當(dāng)块攒，并且符合風(fēng)格指南励稳。
不要在簡短描述中引入列表、圖片或者表格囱井。
請(qǐng)確保簡短描述的簡潔性驹尼！一般字?jǐn)?shù)控制在35字以內(nèi)，極少數(shù)情況下庞呕，50字為上限新翎。
若簡短描述太長，請(qǐng)考慮將部分信息轉(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)系的植康？
請(qǐng)記得：
- 關(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ì)象泳秀、概念标沪？
請(qǐng)記得：
- 簡要給對(duì)象或概念下定義
- 解釋為什么用戶需要理解這一概念
Reference topic中的簡短描述
reference topic 簡短描述寫作指導(dǎo)：
- 這一對(duì)象是做什么的？
- 這一對(duì)象是如何工作的嗜傅？
- 這一對(duì)象用于什么或者為什么它有用金句？
請(qǐng)記得：
- 給對(duì)象下定義或者解釋該對(duì)象是用于做什么
- 說明用戶為什么使用這一對(duì)象
