使用Docsy的更好的文档UX

作者: Zach Corleissen,云原生计算基金会

编者注:Zach是Kubernetes文档特别兴趣小组(SIG Docs)的主席之一。

我很高兴地宣布 Kubernetes网站 现在具有 Docsy Hugo主题.

Docsy主题改善了网站的组织性和可导航性,并打开了改进API参考的途径。经过4年多的时间,UX在有意义的UX改进方面几乎没有,Docsy实施了一些针对技术内容的最佳实践。该主题使Kubernetes站点更易于阅读,并使各个页面更易于浏览。它为该站点提供了急需的整容。

例如:在页面上添加用于导航主题的右侧栏。无需向上滚动即可浏览!

主题为网站的未来改进开辟了道路。我最兴奋的Docsy功能是主题的 swaggerui 短代码,它提供了从OpenAPI规范生成API引用的本机支持。 CNCF与 Google文件季 (GSoD),以便在今年第四季度实现更好的API参考。我们很希望被选中,我们期待着Google在8月16日宣布的项目清单。自从我于2017年首次开始使用SIG Docs以来,更好的API引用一直是个人目标。很高兴看到这个目标可以实现。

SIG Docs的技术主管之一, 凯伦·布拉德肖(Karen Bradshaw) 为解决广泛的网站兼容性问题做了很多繁重的工作,其中包括对我们最后一个问题的修复 遗物 什么时候我们 从杰基尔迁移到雨果 在2018年。我们的其他技术领先者, 蒂姆·班尼斯特泰勒·多尔扎尔(Taylor Dolezal) 提供了广泛的评论。

也感谢 比约恩·埃里克·佩德森,他提供了有关如何进行Hugo升级的宝贵建议 版本0.60.0.

CNCF与 变速箱 在不列颠哥伦比亚省维多利亚市将主题应用到该网站。感谢Aidan,Troy和团队其他成员的所有工作!