深度操作系统-帮助手册-编写规范

  1. Markdown结构规范
1.1 Markdown内容规范
  • 帮助手册统一遵循Deepin-Manual制定的编写规范,采用markdown语法编写。如果编写过程中遇到不能满足实现手册的内容,可向项目负责人或产品经理提出新增需求。
  • 手册中涉及logo图标、章节图标、应用图标、应用界面图标、键盘图标、说明图标、截图图片等均采用设计、开发、文档共同制定的规范。
1.2 Markdown文件层级规范

markdown文件一般提供中英文,其他国家语种一般集成英文帮助手册。

markdown文件夹层级如下:

  • 一级文件夹:deepin-形式,如deepin-repair_V1.0。
  • 二级文件夹common:存放手册logo图标。
  • 二级文件夹语种:中文手册采用zh_CN,英文手册采用en_US。
  • 三级文件夹icon:存放应用图标、应用界面图标、键盘图标、说明图标(统一命名为.svg)。
  • 三级文件夹jpg:存放应用/控制中心/桌面环境等截图图片(统一命名为.jpg),特殊图片可以使用png格式。
  • 三级文档:markdown文件统一命名index.md,存放在对应语种目录下,与icon, jpg文件夹平级。
1.3 markdown图标图片规范
  • 手册图标:采用系统或应用logo图标,大小为96px,命名格式为deepin-xxxx.svg。图标获取地址:/usr/share/icons/deepin/apps/96。
  • 应用图标:采用应用logo图标,大小为24px,在手册中统一命名为deepin-xxxx.svg,强调为手册中应用图标的使用。图标获取地址:/usr/share/icons/deepin/apps/24。
  • 应用自带图标:统一由UI设计师提供,在tower上面创建任务指定给设计师并获取.svg格式。
  • 键盘图标:UI设计师已对键盘26个字母以及其他按键全部绘制设计,手册中直接调用即可。
  • 截图图片:手册编写过程需要截取部分图片作为展示内容,大小根据实际情况而定,保存为jpg格式。
  1. 帮助手册编写规范
2.1 大纲设计

前期了解需求后,理解功能点,从普通用户角度体现手册描述侧重点。

通过思维导图设计大纲结构,待功能点确定后,调整并确定大纲,保持中英文整体结构的一致。

2.2 编写过程

1. 第一阶段:当产品进入需求开发阶段(前期参与讨论和提出问题)时,初步分析功能点以及设计大纲。https://tower.im/projects/f1785043751149989ac3a0077f6e6caf/lists/bf285cb3320d4acba2a2bc6d75978d4d/show/

2. 第二阶段:待需求确定后,进入开发阶段、自测阶段开始文档的编写工作,文档大纲/标题初步检查。

3. 第三阶段:编写文档过程中,及时和翻译人员讨论并确定编写功能点细节。

4. 第四阶段:界面确定后,提交给UI设计师进行美化和绘制。

5. 第五阶段:文档中英文交叉检查,合并图片和图标,并完成归档,然后打包上传。

6. 第六阶段:让开发负责人集成到产品或系统中一起发内测。

7. 第七阶段:后期版本优化或升级维护。

2.3 描述规范
2.3.1 手册标题
  • 标题层级:表示整个文档的框架结构,层级不宜过多。尽量控制在4个层级以内,一般以3个层级为最佳。(例如:4/4.1/4.1.1)
  • 标题长度:表示一个章节的描述主题。短语组成,一般不超过8个汉字。(例如:概述、快捷键)
  • 标题结构:一般情况下,一级标题尽量使用名词性短语,二级标题尽量使用动宾结构短语,三级标题尽量使用动词性短语。
  • 同层级标题:同一个层级的标题最好保持结构一致,如统一使用动宾结构短语、名词性短语等。(调节画面、调整字幕)
  • 文档编写过程中包括专业术语、概念词汇、写作风格等都应做到全文上下统一。
2.3.2 手册正文
  • 手册中涉及到内部和外部链接操作:【具体操作请参阅 [title](#title)和 [title](dman:///manualname#title)】
  • 手册中涉及按钮操作:【点击/双击/点击鼠标右键/右键单击/点选/勾选】
  • 手册中涉及键盘按键操作:【按下键盘上的xxx键/组合键】
  • 手册中涉及鼠标指针操作:【将鼠标指针置于xxx上/ 通过上下滚动鼠标滚轮/按住鼠标左键不放…..将xxxx拖拽xxx….. 释放鼠标左键】
  • 手册中涉及界面折叠/扩展操作:【 在xxxx 折叠框中/ 在 xxxx选项中】
  • 手册中涉及菜单操作:【 点击账户 > 新建账户】
  • 手册中涉及的滑块/滑条操作:【通过左右拖动滑块/滑条来xxxx】
  • 手册中涉及开关按钮操作:【 点击**xxxx**开关按钮 ,开启xxxx功能】
  • 手册中涉及运行应用的操作:点击桌面底部的 ![launcher](icon/launcher.svg) 或将鼠标指针移到屏幕左上角,进入启动器界面。
2.4 手册低检

第一遍:检查标点、错字、句式。有没有错别字,标点符号之类最基本的一些错误。句子成分(主、谓、宾)有没有缺失,句子有没有语病,句式顺序有没有需要调整的。

第二遍:检查步骤。按照自己编写的步骤操作一遍,步骤是否有描述不清楚的。字符串有没有加粗,字符串和图标与前后文字之间是否有空格。

第三遍:检查标题。各个层级的标题是否结构统一,标题是否概括准确。对照需求列表,查看产品功能是否有遗漏没写的。

第四遍:全文架构检查。哪些内容可以合并到一个章节的、每一个章节的顺序调整。

第五遍:全文读一遍,同时文档工程师交叉检查全文。

  1. Markdown工具

编写markdown的工具有很多种,以下介绍各个平台下常用的markdown工具。

Windows:markdownpad2(专业版支持导出pdf)

Linux:Typora(推荐,支持导出word)、haroopad、小书匠

OS X:Mou等

  1. Markdown文件转换为word版用户手册

帮助手册一般转成用户手册时,可以先通过Typora将md文件转换成doc文件后,

通过以下步骤转换图片,然后然后手动替换word中缺失的图标。

  1. 用Typora打开对应的index.md源文件。
  1. 选择 文件>导出,导出为word(需要先安装Pandoc)。
  1. 通过终端命令(sudo apt-get install inkscape)或深度商店下载安装inkscape应用。
  1. 切换到对应帮助手册的icon文件夹目录下,打开终端,执行如下命令
for i in *.svg; do inkscape $iexport-png=`echo $i | sed -e ‘s/svg$/png/’`; done

http://wiki.ubuntu.org.cn/UbuntuSkills

  1. inkscape自动将.svg图标转换成.png文件。
  1. 然后手动替换word中缺失的图标。

发表评论

电子邮件地址不会被公开。 必填项已用*标注