帮助文档的编辑规则

说明

帮助文档是我们平台重要的数字资产，不仅可以可以供用户阅读了解产品功能，还可以作为AI的内容预料。而想要更好的实现以上目标，对帮助文档的内容和排版有更要严格的要求。所以，需要进一步规范帮助文档编辑操作。

文章结构

1、创建帮助文档时标题为一级标题，不需要在正文中额外添加标题，也不能在正文中添加 h1 这样的一级标题。

2、正文中可以使用 h2 、h3这样的标题，也可以加 h4 、h5 、 h6，只是在显示上不会有太大的差别。文章结构也不应该这么多，真的需要这么多的话，就要考虑拆分为多篇文档。

3、正文中的段落使用 p 标签，不同段落使用不同的 p 标签。不得使用换行符来分段。

<p>正文内容</p>

4、正文中可以添加超链接a标签，链接使用新标签页打开，且去除重定向链接。

<a href="a标签" target="_blank">链接</a>

5、图片img标签，标签中设置图片最大宽度为720px，alt属性必须录入，一句话或一个短语描述图片的内容，这个是为了AI可以大概了解图片里讲的是什么。此外，img标签最好外围套一个 p 标签，实现图片独立成行，不和其他正文内容在同一行。

<p><img src="http://helpimage.paperol.cn/2018103115409753301255.jpg"  style="max-width:720px;" alt="" /></p>

6、引用可以使用 blockquote 标签，blockquote 内部使用 p 标签换行。

<blockquote> <p>6.1您在同意本协议授权前，您已经了解并知悉您的数据的重要性，请您认真仔细判断您的数据是否属于可共享至第三方之数据，如您的数据较为重要或敏感，请您谨慎选择。</p> </blockquote>

7、代码内容

<div class="layui-code layui-box layui-code-view" lay-title="html"> <ol class="layui-code-ol"> <li>//1）读取推送的BASE64数据为byte[] encryptedData;</li> <li>byte[] encryptedData = Convert.FromBase64String(encrypted);</li> <li>if (encryptedData == null || encryptedData.Length &lt; 17)</li> <li> return null;</li> <li>//2）取AES加解密密钥作为AES解密的KEY;</li> </ol> </div>

8、视频内容，优先采用B站的「分享」》「嵌入代码」，如：

 <iframe src="//player.bilibili.com/player.html?isOutside=true&aid=114039501886502&bvid=BV1jbAteBE18&cid=28497808408&p=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"></iframe>

关于图片

1、帮助文档中的配图，不得使用base64格式图片，需要通过上传方式获取图片地址，或者联系任亚军获取OSS图床工具和图床配置（PicGo）。

2、使用Windows截图时，必须安装使用「思源宋体」或「思源黑体」的字体，优先使用「思源黑体」。使用包括「微软雅黑」在内的商用字体，造成的版权问题，需要自身负责。

3、截图时，尽量截取有效内容，且不要截图大量空白的区域。如果截图有很大空白，可以先调整显示分辨率再截图。

帮助文档撰写工具推荐

1、本地使用Markdown工具，采用Markdown语言进行协作。这里推荐使用Obsidian这个工具，通过插件可以实现粘贴图片，直接上传到OSS图床。

2、使用秘塔协作猫工具，检查错别字和语法。

3、使用HTML和Markdown互转工具，把Markdown内容转为HTML内容。

4、将HTML内容录入到后台帮助文档正文。

内容要求

1、 帮助文档需要包含：功能介绍、演示示例、设置步骤、注意事项。

2、其中特别需要注意添加「演示示例」环节，演示示例的问卷需要放在selecttemplete用户名下。

3、针对现有的内容进行编辑时，需要直接复制一份现有的内容进行备份。

错误示例

1、在腾讯文档等平台撰写内容，复制粘贴到我们平台。内容里包含大量的行内样式。

2、大量采用 br 标签进行换行，而不是p标签。

3、图片不添加Alt属性。