「K4NZ」- 文档分类(博客规范)

更新日期:2020年01月14日
@IGNORECHANGE @SPEC

根目录技术分类

类型 等级 描述
00.INDEX   最近更新的文章,这是笔记的一个简单介绍页面。(用Python脚本生成)
# 基础知识 # 01-05 底层技术及基本知识。比如网络知识,编程语言,操作系统,硬件知识等等。
# 技术应用 #   基础技术的应用。比如容器技术,爬虫技术,数据库技术,软件工程等等。
# 管理方法 #   软件工程是一个例子。它用到了某些技术,但是更多的是一些管理方法相关的内容。
z.All Uncategorized Articles...   未分类的杂记

该分类的划分依照是「我个人对各种技术关注度」,并不是标准,每个人都可以自己的分类喜好。与软件应用相比,我更喜欢计算机技术,更喜欢研究硬件、操作系统、网络、算法等等基础技术。应用技术,比如软件开发、监控、数据库、容器等等,变化块、投入产出比相对较低、依赖于基础技术,也只是为了解决问题才学习。当然,每种技术,不管是发明它,还是学习它,都是为了解决某个问题。

章节结构(技术文章)

# Category Name(Introduction) - 标题页面包含了最开始的简单介绍及基本原理组件,用于辅助安装部署。

# 1.Concepts and Architecture - 使用方法及基础概念
# 2.Installation
# 3.Administration and Configuration
# 4.Security
# 5.Performance
# 6.Logging and Monitoring
# 7.Cluster and High availability
# 8.Backup
# x.Miscellanies
# 0.Books and Forums
# z.Error List
a.由于管理不善而引发的错误,属于「3.Administration and Configuration」部分。

目前按照此目录结构整理某技术笔记。

文章内容类型

鉴于官方文档及RFC等等文章己经非常完善,我们能够编写的文章总共以下几类:

为理解原理写文章,讲述某技术背后原理。这是对官方内容的简述,或是为了加深理解,或是为了简单表述。

为解决问题写文章,讲述某些操作。这是对官方内容梳理,记录我们常用操作,当然也包含日常杂记。

为实现功能写文章,记录创造、想法、发现。使用知识进行发明创造,也是激动人心的地方,因为你总能发现一些诡异的玩法。

# 切忌翻译文档
(1)直译官方文档已经背离写作初衷。
(2)翻译文档是为了与他人分享,而我们写作的目的并不是为了分享官方文档。
(3)另外……翻译文档还不如劝人学习外语。

# 切忌事无巨细
(1)再详细也不会超过官方文档。
(2)对于操作说明(说明书)性文章,核心在于“章节标题”。“章节标题”需要体现操作目的,而“章节内容”只需要概述操作过程。
(3)在内容中,切忌列举达到某以目的的多种方法。

文章结构

章节标题 作用
# 文章标题 「类别」- 概述文章内容
内容简介 内容简述:(1)简述问题。(2)简述内容。
问题描述 详细描述问题(也是写作本文的原因)。
解决办法 问题的解决办法。
文章正文 解决办法的详细过程。如果内容简单,可以与「解决办法」章节合并。
附加说明/注意事项 附加说明,或者注意事项。
相关链接 在完成本文的过程中所相关的文章。
参考文献 参考内容,对引用内容的标注。

文章标题 - 需要指明类别,并用一句话概述文章内容。
内容简介 - 因为「内容简介」部分与「问题描述」部分通常会重叠。两者只能出现一个,不能同时出现。
问题描述 - 描述需要处理的问题,即写作本文的原因,并用一句话点题。

文章标签

标签名 标签作用 文章价值
IGNORECHANGE 忽略更新 内容混乱,属于技术杂记、或者某主题主页。(不具备参考价值)
UNRESOLVED 问题未解决 具有解决某些问题的参考价值,但是存在很长严重未解决问题
FINISHED 已完成 文章内容以完善,可知道解决某一问题
SCRIPT 脚本 文章内容为常用脚本,用于解决某些问题。



ToC

根目录技术分类

章节结构(技术文章)

文章内容类型

文章结构

文章标签