0
点赞
收藏
分享

微信扫一扫

【悟空编辑器】从技术博客的内容结构指导技术文档的编写

在上一篇中,我们为了分析技术博客的内容结构,开发了内容结构提取工具,写作的过程中自然激发了论文写作的检查流程,然后就想到能不能基于技术博客的内容结构,给技术博客的编写提供指导建议呢?

1 研究思路

s=>start: 开始
e=>end: 结束

op1=>operation: 查找HTML文档结构规律
op2=>operation: 列出常用文档片段结构
op3=>operation: 给出文档片段检查建议

s->op1->op2->op3->e

2 查找文档结构规律

2.1 内容的标签结构

HTML 是结构化语言

结构化是指 HTML 页面的框架部分是结构化的,有明确的包含关系,例如:

<html>
	<head>
		<meta ... />
		<title>Sample</title>
	</head>
	<body>
		
	</body>
</html>

HTML 是扁平化语言

扁平化是指 HTML 页面的内容部分是扁平化的,标题、内容处在同一等级,例如:

<h2>研究背景</h2>
<h3>国内现状</h3>
<p>xxx话题近几年被广泛提及,最早对它大规模推广的是...</p>
<p>...</p>
<h3>国外现状</h3>
<p>xxx在欧美的应用比较早,但由于xxx原因,局限于xxx范围。</p>
<p>...</p>
<h2>研究内容</h2>
<p><img /></p>
<h2>实施方案</h2>
<h3>硬件设备</h3>
<p>...</p>
<h3>实施团队</h3>
<p>...</p>
<h3>实施周期</h3>
<p>...</p>

使用标签来描述内容性质,使用 xpath 表示所属关系,可以表示为 h2, h3, p, p/img

假如我们使用空格表示前后关系,使用 < 表示下级关系,使用 > 表示上级关系,那么可以使用 h2 h3 p p h3 p p h2 p < img > h2 h3 p h3 p h3 p 表示结构。

了解了这个特点后,我们可以做出基本的判定:

  • 主要内容是扁平化结构
  • 结构化的标签描述的主要是组件

2.2 常用语义化标签

HTML 标签比较丰富,有些有特定含义,有些可以通用。此处本文选取语义化标签。

顶级标签

  • 使用 h2-h5 表示 2-5 级标题
  • 使用 p 表示内容(内部用正文行、正文块)
  • 使用 blockquote 表示引用(内部用正文行、正文块)
  • 使用 pre/code 表示代码块
  • 使用 ul/li 表示无序列表(内部用正文行)
  • 使用 ol/li 表示有序列表(内部用正文行)
  • 使用 table/thead/tbody/tr/th/td 表示表格(内部用正文行、正文块)

2.3 正文行标签

  • 文字
  • 使用 a 表示超级链接
  • 使用 code 表示行内代码
  • 使用 strong 表示强调
  • 使用 em 表示倾斜
  • 使用 ins 表示下划线
  • 使用 s 表示删除线

正文块标签

  • 使用 img/figure 表示图片
  • 使用 video 表示视频
  • 使用 audio 表示音频

不建议

  • 不建议使用 h1,标题即 h1
  • 不建议使用 h6 或者以后标题,导致层级太深
  • 不建议修改默认字号,破坏阅读观感
  • 不建议使用多种自定义颜色,扰乱色彩体系

3 常用文档片段

3.1 团队技术文章

样本:腾讯云技术文章

选取文章深入解读Raft算法与etcd工程实现,内容节点为 .J-articleContent,路径和使用数量如下:

blockquote < p >                        1
div < pre < code < span > > > button >  8
figure < div < span > >                 30
h3 < strong >                           11
h4 < strong >                           23
ol < li >                               20
p                                       52
p < a < strong > >                      1
p < a >                                 1
p < strong >                            4

样本:阿里云技术文章

选取文章阿里云高性能计算负责人何万青:阿里云大计算加速HPC与AI融合,内容节点为 .lake-engine-view,路径和使用数量如下:

p < strong strong < span > strong < span > >  1
p < span < span < span < span < span < span < span < span < i < svg < path path > > > img span < span > > > > > > > > >24
p < span >                              1
p < br >                                40
p                                       28
p < strong strong >                     1
p < strong < span > >                   7
p < strong >                            6
p < strong < span > strong < span > >   1
p < span strong < span > >              1
p < a >                                 1

样本:百度云技术文章

选取文章亿元免费算力 | 百度大脑AI Studio重磅推出算力支持计划,内容节点为 .markdown-body,路径和使用数量如下:

p < span < img > >                      11
                                        74
p                                       35
p < span >                              21
p < span < strong > >                   4
p < a < img > >                         1
p < span < strong strong > >            1
p < img >                               1
p < span < a > >                        1

这里空白标签是因为使用了<p>&nbsp;</p>作为空行,显然是文章粘贴转写的原因。

样本:美团技术博客

选取文章深入理解函数式编程(上),内容节点为 .content,路径和使用数量如下:

p                                        56
p < strong >                             47
p < img >                                42
h4                                       12
h3                                       6
h2                                       5
ul < li < strong > >                     4
blockquote < p < strong > >              3
ol < li < strong > >                     2
ul < li >                                2
p < strong < a > >                       1

选取文章大规模异构图召回在美团到店推荐广告的应用,内容节点为 .content,路径和使用数量如下:

p                                        23
p < strong >                             14
p < img >                                12
h2                                       9
p < sup >                                6
h3                                       2
ul < li >                                2
p < strong sup >                         1

样本:字条跳动的掘金博客

选取文章构建可扩展模型的几种方案,内容节点为 .markdown-content cache,路径和使用数量如下:

p                                        14
h3                                       7
ul < li >                                6
h2                                       4
h1                                       3
p < img >                                2
ol < li >                                2
table < thead < tr < th > > tbody < tr < td > > > 2
style                                    1
blockquote < p >                         1
blockquote < p < a < strong > > >        1
ul < li < em > li < em > >               1
h1 < strong >                            1

样本:火山引擎技术文章

选取文章CDP市场将迎新增长 火山引擎VeDI旗下的这款产品推出多项新动作,内容节点为 .markdown-body,路径和使用数量如下:

p                                        13
p < em >                                 2
p < img >                                1
p < a >                                  1

3.2 个人博客

样本:阮一峰博客

选取最新一期的电子周刊,内容节点为 #main-content,路径和使用数量如下:

p                                        77
p < a >                                  65
p < img >                                49
h2                                       13
p < code >                               2
blockquote < p >                         1
p < strong >                             1
p < a < code > >                         1
iframe                                   1

样本:廖雪峰教程博客

选取文章构建可扩展模型的几种方案,内容节点为 .x-wiki-content x-main-content,路径和使用数量如下:

p < code >                               15
pre < code >                             9
p                                        7
h3                                       2

样本:Joyee Cheung's Blog

选取文章Fixing snapshot support of class fields in V8,内容节点为 .post-content,路径和使用数量如下:

figure                                   12
p < code >                               12
p                                        7
h3 < a >                                 2
p < a >                                  1
p < code a code >                        1
p < img >                                1

4 文档片段检查

4.1 对样本的基本分析

好的

  • 主体基本都是规范的
  • 引用是一致的
  • 代码块是一致的
  • 段落是一致的

不好的

  • 标题使用不太规范,有的没有 h2,有的使用 p strong 代替 h3/h4,有的标题中存在 strong
  • 使用空行当作段落间距
  • 图像标签的使用存在多层嵌套的情况,较为复杂

4.2 推荐的文档片段检查建议

关于标题

  • 文章标题为 h1
  • 文中标题从 h2 开始
  • 文中标题有合理的层级,中间不跳级
  • 标题不含其他标签

关于引用

  • 使用 blockquote 标签
  • 引用中的内容放在段落内

关于列表

  • 列表使用 ol/ul 标签
  • 列表中允许文字
  • 列表中允许链接 a
  • 列表中允许代码行 code
  • 列表中允许强调strong、斜体em、下划线ins、删除线s

关于图像

  • 普通图片放在 img
  • 学术/技术图片可以放在 figure

关于段落

  • 不使用空行
  • 正文应在段落内
  • 图像 img/figure 应在段落内
  • 代码块 code 应在段落内
  • 段落中允许强调strong、斜体em、下划线ins、删除线s

关于代码块

  • 建议使用 pre/code
  • 不建议层层嵌套

关于表格

  • 建议按标签规范使用
  • 建议存储短文本、数字
  • 不建议存储大量文本内容
  • 不建议存储图片
  • 不建议存储代码块

4.3 典型场景附加建议

短讯、短评

此类文章比较简单,一般不需要建议。

  • 文字,多个段落
  • 图文,至少一张图 + 多个段落

长技术文章

此类文章写作时耗时多,可以启用建议。

  • 代码块:建议代码不超过30行,源文件较长时附加源码链接
  • 图片:建议图片采用实际格式(较小)或者自适应宽度模式(较大)
  • 表格:单个单元格长度内容长度少于50,内容超多的单元格小于10%
举报

相关推荐

0 条评论