wudonger
(Wudonger)
1
================================专项介绍 =================================
一、文档中心体验优化
1. 背景问题
老版文档中心存在一套文档融合所有业务场景，文档堆砌、内容组织混乱的问题；用户无法从当前文档体系中快速查阅自己关心的文档。
2. 解决方案
产品文档架构重构：按业务场景、分用户角色对产品文档架构进行重构，改变一套文档融合所有内容的现状，将资料拆分成6大业务场景，7个工具模块，包括70+本手册。
3. 优化进展及效果
新版文档中心已随openEuler 25.03版本上线。
二、文档生产发布机制优化
1. 背景问题
在老版的文档生产机制中，所有的文档均在openeuler/docs仓进行生产和发布。
（1）对于特性SIG成员：
- 与doc SIG沟通审批效率低，文档更新滞后。
- 须遵守公共docs仓流程规范，自由度低。
- 学习公共docs仓结构、合入流程，贡献门槛高。
（2）对于Doc SIG成员：
- 协调各特性 SIG 的文档合入，管理压力大。
- 责任界定模糊，问题难以得到快速解决。
- 专业知识局限，降低文档的准确性与完整性。
2. 解决方案
文档生产下沉至各SIG组。
（1）文档生产：之前所有文档都集中存于 docs 仓。改版后：
- 基础特性文档：如安装、升级等通用配置类文档依旧放在 docs 仓，由 doc SIG 集中管理。
- 增量特性文档：如A-Tune、oeAware 等拓展系统功能的文档，在各 SIG 组的代码仓维护。
（2）文档发布：
- 各 SIG 组在代码仓存放特性文档的文档内容文件（即实际文档内容）和目录结构文件(_toc.yaml ，即章节结构）
- 将手册【目录结构文件】的引用，添加到对应业务场景或工具的【目录结构文件】中，特性文档即可发布构建到网站页面。
3. 优化进展及效果
在openEuler 25.03版本的文档中，新版文档生产机制已在sig-ai和sig-openStack完成推广并落地实行。改版后有如下好处：
（1）对于特性SIG成员：
- 在自己的代码仓内灵活管理文档。
- 修改代码时可及时更新文档。
- 降低参与门槛，提高贡献意愿，提高文档的质量和数量。
（2）对于Doc SIG成员
- 减轻doc SIG文档收集、整合、协调工作负担，聚焦文档规范制定、审核等核心工作。
================================交流讨论 =================================
社区例会
会议主题：openEuler 文档改版升级
会议时间：每周一14:15-15:15
会议内容：openEuler 文档改版升级工作进展与风险
联系我们
邮件列表：doc@openeuler.org
doc仓：https://gitee.com/openeuler/docs
访问地址
文档中心：https://docs.openeuler.openatom.cn/zh/
3 Likes
wudonger
(Wudonger)
2
==============================专项进展250521 ==============================
一、概述
【总体进展】
VSCode插件开发已实现两类低错问题检测，持续优化扩展中；新版文档生产机制已在8个SIG组推行、覆盖30+本手册，各SIG组有序推进落地中。
【上一周工作进展】
(1) 文档生产下沉至SIG组：
- SIG组推广实行：新版文档生产机制已在8个SIG组启动推行，覆盖30余本手册。目前各SIG组正有序推进落地，预计于25日前确定具体实施方案，6月10日前完成全量迁移工作。
- 构建方案：已完成基本功能，预计25号前可以正式上线。
- 流水线门禁：已确定方案，本周可以开始配置。
(2) 文档内容优化：本地插件开发中，已实现markdownlint、闭合问题检测。
(3) 老版本更新：24.03 LTS SP1版本文档仓完成重构，待构建验证并发布到网站。
【下一周重点工作】
(1) 文档生产下沉至SIG组：
- 与SIG组确定实行方案，包括文档存放的代码仓及目录结构安排等。
- 构建方案：正式上线。
- 流水线门禁（代码和文档区分）：陆续为已确定方案的代码仓进行配置。
- 翻译issue：代码仓文档要区分是否发布至官网，本周对齐方案和完成时间。
(2) 文档内容优化：
- vscode插件开发：发布使用，集成ci流水线中其他检查项；
- 优化文档《安装指南》，持续完善问题集；
(3) 老版本更新：完成24.03 LTS SP1构建测试。
【测试问题进展】
通过易用性测试、业务走查、内部跳伞、odd大会等多渠道，共收集210+条有效问题，当前已经闭环重要问题147条，17条问题作为专项工作跟踪进展，剩余46条问题待处理。
待解决的重要问题：
- 文档开发指南优化：①场景和手册对应关系②架构调整，快速入门提前③内容简化，步骤流畅④考虑是否添加视频⑤加入图片规范、流程图、表格等写作规范——5/30
- 搜索优化：①搜索的版本问题②优化搜索提示语——5/30
- 提供高效便捷的交流讨论和文档反馈入口，降低反馈门槛——5/30
- 文档预览功能：以vscode插件形式实现——6/30
已解决的TOP重大问题：
- 文档开发指南优化
- 文档易用性问题整改，如用户反馈文档不够精简、引入名词过多，架构待优化等
- 文档准确性问题整改，如链接错误、格式问题、大小写统一、标点符号等
- gitee目录难对应优化：将贡献文档部分内容放在了gitee里
- UI视觉类问题：改善了标题分级不清晰、白底蓝字显示不清晰、反馈按钮不一致的问题，增加了配图放大按钮
- 文档搜索优化：改善了搜索结果未过滤的问题，文档搜索不引用站外结果
- CI门禁优化：缩短门禁时间；改善反馈不清晰的现状，优化为表格反馈，并将错误标红
- 完成对全量文档的第一轮走查：标点符号错用、格式不规范、链接错误等100+条问题已发现并修复
二、里程碑
三、详细进展
gzbang
(gzbang)
4
wudonger
(Wudonger)
6
==============================专项进展250526 ==============================
一、概述
【总体进展】
VSCode插件已集成docs仓现存CI检查项，待发布并进一步扩展功能；新版文档生产机制已在8个SIG组落地推行，覆盖30余本手册，各SIG组已明确迁移方案，正有序推进迁移工作。
【上一周工作进展】
(1) 文档生产下沉至SIG组：
- SIG组推广实行：8个SIG组的迁移方案已确定，剩余3个SIG组的方案预计本周内完成，文档迁移工作正在有序推进中。
- 构建方案：已正式上线。
- 流水线门禁：已配置ai-sig和cloudnative-sig代码仓的文档流水线。
(2) 文档内容优化：VSCode插件已集成docs现存的ci检查项（除codespell）。
(3) 老版本更新：24.03 LTS SP1版本文档已构建发布至测试环境，测试验证中，预计英文翻译6.8前完成，6.20前正式发布。
(4) 测试问题修改：测试收集的210+条有效问题中，已闭环166条，待处理32条。本周主要处理文档开发指南优化相关问题：①场景和手册对应关系②架构调整，快速入门提前③内容简化，步骤流畅
【下一周重点工作】
(1) 文档生产下沉至SIG组：
- 剩余3个SIG组确定文档迁移方案，文档逐步迁移。
- 流水线门禁（代码和文档区分）：陆续为已确定方案的代码仓进行配置。
- 翻译issue：本周对齐方案和完成时间。
(2) 文档内容优化：
- vscode插件开发：发布使用，实现toc自动生成功能；
- 优化文档《安装指南》，持续完善问题集；
(3) 老版本更新：24.03 LTS SP1测试验证，修复问题。
二、里程碑
三、详细进展
新版文档看着美观很多，希望老版本的文档皮肤也能尽快更新，期待 
xialu7373
(Xialu7373)
10
期待VSCode文档检查插件、文档修改效果提前预览的功能
1 Like
liyongle
(Liyongle)
11
gzbang
(gzbang)
13
文档插件“Doc Tools”已发布试用版本，欢迎各位下载使用并反馈
ps: 目前仅支持vscode版本>1.100
下载安装：
vscode插件搜索“Doc Tools”，点击安装
变更说明：
openEuler/docs文档在开发者提交PR时引入了自动化检视工具，对文档中低错问题进行排查。
开发者提交PR后，会自动触发门禁进行检查。当返回如下结果时表示已经通过了工具检查：
该门禁会检查每次提交PR中，该仓库根目录docs文件夹中的Markdown文件。具体检查规则可以通过openEuler官网的文档中心查看 文档开发流水线门禁 | 文档 | openEuler社区
wudonger
(Wudonger)
15
插件试用了几天，确实减轻了文档开发负担，它集成了所有 CI 检查项，提交 PR 前就能发现并修复markdownlint、链接错误等问题，避免提交pr后反复修改。
插件还支持标签闭合问题和拼写问题的快速修复，节省修改时间~
插件还有很多的优化空间，例如spelling-lint的误报率较高，如下图所示，命令行中的"makecache" 和 “gitee” 等专有名词会被标记为拼写错误。
再比如，可以加入“支持用户按需勾选需要启用的检查规则”功能，能更好地满足不同场景下的开发需求。
期待插件的功能越来越好~
wudonger
(Wudonger)
16
==============================专项进展250609 ==============================
一、概述
【总体进展】
基于VSCode的文档开发插件已发布，集成了docs仓现存CI检查项；新版文档生产机制已在8个SIG组落地推行，覆盖40余本手册，文档迁移已完成80%。
【上一周工作进展】
(1) 文档生产下沉至SIG组：
- SIG组推广实行：80%已完成文档迁移，剩余4本手册pr检视中，4个未提交pr。
- 流水线门禁：已全部配置完成，实现 SIG 代码仓文档与代码 CI 解耦。
(2) 文档内容优化：
- 发布基于VSCode的文档开发插件，已集成ci检查项，doc-sig试用中。
- 通过大模型工具扫描，共发现并修复文档问题约250+条，其中top问题包括标点符号问题、多余空格问题、图片格式问题等。
(3) 老版本更新：2403 LTS SP1 中文文档测试完成，共发现并修复问题150+；英文文档已基本完成，待解决流水线问题并合入。
【下一周重点工作】
(1) 文档生产下沉至SIG组：
- 检视文档迁移pr，完成所有sig的文档迁移。完善细化规范和要求，审视迁移文档质量。
(2) 文档内容优化：
- vscode插件开发：收集并修复使用问题，实现toc自动生成功能；
- 问题集：检测并修复2403 LTS SP1文档问题，完善问题集。
(3) 老版本更新：24.03 LTS SP1测试验证，修复问题；修改英文文档流水线问题。
二、里程碑
三、详细进展
wudonger
(Wudonger)
17
==============================专项进展250623 ==============================
一、概述
【Q2总体工作进展】
(1) 建立文档生产、发布机制：
- SIG组推广实行：新版文档生产机制已在 8 个 SIG 组推行、覆盖约50手册，占比超50%。新机制下，各 SIG 文档贡献量、PR 检视意见量增加，驱动文档质量提升。已激励首批参与文档体验改进的开发者。
- 流水线门禁：已全部配置完成，代码仓门禁实现代码和文档区分。
- 构建方案：支持单版本构建，构建耗时更稳定、策略更灵活。
(2) 通过工具提升文档质量：
- 文档写作过程中：搭建文档开发环境，发布基于VSCode的文档开发插件，已实现top问题的检测及修复（包括markdownlint、链接失效、标签闭合等问题，与docs仓ci一致） ，doc-sig内部试用中；
- 文档仓扫描：通过大模型工具扫描重点文档，共发现并修复文档问题约250+条，其中top问题包括标点符号问题、多余空格问题等。
(3) 老版本更新：
- 按最新的资料架构，计划完成4个版本的更新改版，目前已完成3个，包括文档仓重构及构建问题整改。（ openEuler 25.03（已完成）、24.03 LTS SP1（已完成）、24.03 LTS SP2（已完成） 、 22.03 LTS SP4 ）
(4) 文档生产机制复用：
- 已经推广给openUBMC文档负责人，需进一步总结生产机制，形成分享材料。
【下一步】
(1) 建立文档生产、发布机制：
- 文档生产新机制覆盖所有SIG组，贡献者按照新的资料生产和发布方法运作，激励开发者做文档贡献 。
- 更新文档写作规范，优化文档检视及测试流程，保障 SIG 下沉后的文档质量。
(2) 通过工具提升文档质量：
- 针对文档写作检查的VSCode插件放开给开发者使用，对插件易用性进行快速优化。
- VSCode插件功能扩展，添加文档预览，语义优化等功能，持续发现并梳理文档规范性问题，集成到ci流水线及插件中。
(3) 老版本更新：
- openEuler 24.03 LTS SP1、24.03 LTS SP2 测试上线。（630前）
- 历史版本openEuler 22.03 LTS SP4文档的更新改版工作。
【测试问题进展】
通过内外部跳伞、odd大会等多渠道，共收集200+条有效问题，已闭环179条，剩余26条处理中，已解决的重点问题如下：
| 问题类型 |
详情 |
| 文档开发指南优化 |
文档易用性问题：文档不够精简、目录架构不清晰、内容不连贯等；文档准确性问题：链接错误、格式问题、大小写统一、标点符号等 |
| gitee目录难对应优化 |
优化文档仓库存储结构，gitee仓加入相关说明 |
| UI视觉类问题 |
统一了注释符号样式、制定图片规范、改善了标题分级不清晰等 |
| 文档搜索优化 |
改善了搜索结果链接失效、搜索结果未过滤等问题、优化搜索提示语等 |
| CI门禁优化 |
去除非必要检查项；缩短门禁时间；改善反馈不清晰问题等 |
| 文档内容问题 |
发现并修复标点符号、多余空格、图片格式等文档问题约250+条 |
待解决重点问题如下：
| 问题类型 |
详情 |
| 文档预览功能 |
集成到VSCode插件中 |
| 文档开发指南优化 |
内容补充：加入视频、表格规范、图片规范等；内容调整：内容精简、连贯性调整等 |
| 文档内容补充 |
补充虚拟镜像的安装指导、DevStation的安装界面指导等 |
二、里程碑
三、详细进展
新文档很不错
