前言
2023年Zephyr开发者大会（ZDS）于6月27日至30日在捷克布拉格隆重举行。与以往两次不同，本次ZDS由Zephyr项目规划和管理，并作为首届嵌入式开源峰会（EOSS）的一部分进行。在这个令人期待已久的盛会中，全球Zephyr开发者们共同探讨了Zephyr实时操作系统（RTOS）的最新技术与发展趋势。作为一款开源、灵活和可扩展的嵌入式实时操作系统，Zephyr项目在2014年由英特尔发起，2016年作为Linux基金会项目正式面向公众启动，得到了全球范围内的广泛关注和采用。
ZDS 2023共70余个技术报告，涵盖了使用指导与展示、新功能与技术、架构修改与操作系统、多核异构与虚拟化、模拟器、测试、工业流程与代码管理、安全性、应用案例、工具与调试等丰富多样的内容。湖大嵌入式实验室的小伙伴们将对本次大会的所有技术报告进行逐一收集、整理与分享，尽最大努力为Zephyr开发者提供ZDS 2023技术报告的开发经验、实践成果以及解决方案的参考。
今天分享第43篇技术报告，由王渊整理，题目为：
“关于Zephyr文档的BoF会议”
作者简介
Benjamin Cabé是一名技术爱好者，热衷于帮助开发人员构建创新的解决方案。他在领导物联网、嵌入式和人工智能领域的一些顶级社区和公司的开发人员参与计划方面拥有超过15年的经验。他发明了一个屡获殊荣的开源和开放硬件人工鼻，他喜欢将它用作对嵌入式开发世界感兴趣的人的教育平台。他目前是Linux基金会Zephyr项目的开发者支持者，住在法国的图卢兹（Toulouse），在那里，他喜欢借助自己的人工鼻子烘焙酸奶面包。
文章简介
Zephyr RTOS文档对于开发人员来说是重要的资源，但有时要找到所需的详细信息可能会很困难。本次 BoF会议旨在将Zephyr维护者、开发人员和用户聚集在一起，讨论改进Zephyr RTOS文档的方法。我们将讨论开发人员角色、文档结构、组织以及有助于简化文档流程的潜在工具和流程等主题。
我们在2023年五月到六月期间上线了一个关于文档的调查，从5月26日截至到目前我们收集到了多于85份问卷结果。因为调查是在Discord/social的媒体和博客里面推广的，所以来自这些特定群体的反馈可能存在一些偏见。我们的调查内容包含以下几个方面：
我想要根据反馈更深入地研究一些主题。例如搜索、导航、全面的samples/tutorials、How-to's/Best practices，以及是否提供PDF，是否可以下载到本地。
在收到的反馈中，受访者认为Zephyr文档存在一些他们喜欢的东西。比如说依赖于Zephyr 所有领域的许多维护者，Zephyr文档总是最新的、广泛的、真实的，它包含的代码可以更好地说明、拥有许多“人工写的”有用的架构文本描述和图等，以及其中一些可以解决痛点的samples。
当然，Zephyr文档中实际也存在很多痛点（包含正在修复和已经修复的）我也想深入探讨一下。比如使用Google搜索引擎尝试搜索Zephyr相关信息，你可能会得到一些旧版本的文档；使用内部网页搜索结果的准确性和搜索结果排名都可以做的更好。以及人们希望能够有更多的教程/最佳实践/详细的操作方法，同时存在一些板块文档比其它板块好的问题。而对于贡献者来说，他们也反馈了一些问题。比如说本地构建文档的文档不全、速度慢，图表不可编辑都是一些存在的痛点。
“当你从谷歌搜索中输入文档时，你通常会得到一个较旧版本的文档。”我们已经对这一问题做了修复，所以现在的情况应该好多了！具体通过以下几种方式实现：
更新robots.txt；
明确要求谷歌删除旧版本的URLs；
清理了导航菜单只列出支持的版本，即当前LTS 加上过去的几个版本。
以下是对这个问题进行修复前后的一个统计示意图。当人们搜索如何使用Zephyr创建线程时，修复前他们将被搜索引擎带到各个版本，比如说2.3、2.4、2.5之类的；现在希望当用户搜索这些信息时，他们要么只被带到Zephyr 最新版，要么被带到LTS版本。
2. 现代化的主题
参考Sphinx Immaterial主题，这改编自流行的mkdocs-material主题。它拥有现代化的界面，集成了Mermaid.js，并且我们改进了搜索能力。
3. 可编辑的图表
我们嵌入了Mermaid.js框架，在Demo中快速演示如何进行图表编辑。
4. 性能改进
即使你有一个非常好的机器上，在本地从头开始构建可能也需要十几分钟。针对这个问题，为了本地构建文档时获得更好体验，我们提出了两个关于性能改进的Pull Request（PR）：
5. 可导航性/可发现性
“对于一些高级页面，如PWM，我建议有一些指向活动样本的链接。”虽然API引用很重要，但作为一名开发人员，有时候只是想复制代码，这就产生了如上这种需求。
6. 内部搜索
1. 搜索词统计
2023年5月的搜索数据显示，其中有218K次访问以及30.6K次内部搜索。被搜索最多的前10个关键字数据如下：
2. 板块访问
来自23年5月的直接访问板块文档页面的用户（而不是使用内部搜索的用户）最多访问的板块如下：
如果您知道任何其他在某些方面做的很好的开源项目（如下为例），我很乐意在不久后收到您的来信，并希望从中获得灵感。我认为接受来自外界的良好反馈，并受到其他人的启发很重要。
