夜雨聆风
计算开发者文档“五易”升级,开发效率从此快人一步!
华为计算产品面向不同用户角色提供了差异化的信息体系，主要有三类，第一类是面向客户的产品信息体系，主要围绕计算硬件产品、解决方案通过华为技术支持网站提供产品售后资料。第二类是面向开发者的生态信息体系，主要围绕鲲鹏、昇腾开源开放软件产品通过开发者社区提供开发类文档、学习实践资源，以及开发者贡献文档。第三类是面向伙伴的使能信息体系，主要围绕鲲鹏昇腾OEM部件产品提供使能伙伴进行整机二次开发的资料。
2025年我们聚焦面向开发者的信息体系做了全新升级，包括易实践、易上手、易获取、易求助、易阅读5大提升点，同时在文档共建方面也有一些实践探索，希望联合产业开发者为计算产业添砖加瓦。
一.易实践
针对开发者最关注的4大开发场景，例如昇腾的训练开发、推理开发、算子开发，鲲鹏的同辕开发场景，我们全新构建了场景化主页，围绕这些核心开发场景的开发任务，汇聚开发过程所需资源，提供全链路导航，让开发者聚焦当下开发任务，快速获取所需资源。
匹配前面提到的场景化主页，我们同步上线了15+场景级开发指南，将开发相关的软件包、镜像、快速入门、开发指南、代码样例、课程等资源按照用户场景归一化呈现，信息轻量化，开发者可以拿来即用，极大的降低了开发门槛。
二.易上手
通过开展燎原行动文档专项改进，聚焦开发者高频使用的核心文档，围绕文档正确性、完整性、易理解性进行优化，例如正确性方面通过内部自验证、大模型检测工具扫描等及时修正操作步骤、操作命令错误问题、描述不一致等问题；完整性方面通过checklist自检、VOC驱动等持续补充完善参数含义、配置建议、约束限制、使用教程等内容；易理解性方面通过专家团队走读评审调整优化文档大纲结构，内容逻辑，显性化关键信息，让文档更符合开发者使用习惯。通过这些改进措施，文档Bug类问题已经逐步在下降。
三.易获取
针对开发者反馈的文档更新不感知的痛点问题进行了改进，通过构建公告板块，将文档变更信息通过版本级公告、文档节点最新动态、单本文档内修订记录三层架构纰漏给开发者，同时结合社区分层推送机制，将核心变更内容通过EDM邮件主动推送精准触达给客户，例行刷新内容通过社区订阅能力传递，减少信息滞后产生的风险。
四.易求助
社区提供丰富的技术支持途径，例如阅读文档过程发现文档有问题或者有疑问，可以在线评分反馈或提单，提单时支持关联社区海量案例库资源，类似案例可以作为参考，开发者无需重复提单，节省开发者查找资源的时间。同时我们也会将开发者咨询求助的问题转化为常见问题或故障案例，持续丰富案例资源，帮助开发者快速解决问题，降低试错成本。
五.易阅读
我们对产品级文档使用导读进行了升级。导读页作为产品信息第一入口，汇聚文档资源，我们通过优化导读的信息层级，并按照能力阶梯分层分类，开发者通过导读页即可获取所需信息模块，即取即用，无需学习文档设计逻辑。
同时通过科学的人因理论数据和实践分析，对社区文档目录层级结构、正文标题、文字、间距、表格字号、行高、列宽等原子级组件和规范进行了升级，提升了阅读区信息密度，匹配开发者阅读习惯。
匹配计算鲲鹏昇腾软件开源策略，我们也在探索软件开源后，配套的开源文档如何联合开发者一起参与贡献的机制。让开发者从文档使用者，逐步成为文档贡献者。一方面开发者社区构建文档PGC、UGC机制、平台、工具、流程指导、物质激励、能力认证等资源，借助社区各种运营活动和社区KOL、业界大咖、TOP ISV等的知名度和影响力，希望带动更多开发者参与文档贡献，促进技术交流和知识传递，也让开发者的能力能够变现，最终形成共建共享的良性循环。
在openEuler开源社区运作过程中，逐步总结了一些文档共建的机制，例如通过将特性文档下沉到各个SIG组，定义统一的文档开发指南和写作规范，包括git基础操作指导、文档目录存放结构设计指导、文档内容增删改操作指导等，step by step指导开发者快速上手进行二次开发。
开源文档写作过程中，我们也自研了基于VS Code插件版文档质量检测工具，通过在插件端即可一键安装该工具，开发者使用MarkDown写文档时，能够边写边检查，例如错别字、拼写错误、MarkDown语法、html标签闭合等基础质量检测，同时针对检测出来的错误提供快速修复能力，辅助开发者提质提效。
25年我们聚焦开发者社区文档围绕易实践、易上手、易获取、易求助、易阅读进行了体验升级，未来我们会继续倾听开发者声音，持续深耕打磨文档体验，携手开发者共建共享文档体系，繁荣生态，共创行业新价值，让我们的开发者文档体系在迭代中不断生长。
