OCaml.org 新闻通讯:2023 年 4 月
欢迎阅读 2023 年 4 月版的 OCaml.org 新闻通讯!与之前的更新一样,这份通讯由 @sabine 和 @tmattio 共同整理。
OCaml.org 新闻通讯概述了 OCaml.org 网站上的变化,并让你了解幕后发生的事情。你可以在此处找到往期内容列表。
我们的目标是将 OCaml.org 打造为任何想要入门并高效使用 OCaml 的最佳资源。如果没有所有帮助我们审查、修改和创建更优质 OCaml 文档的优秀 OCaml 社区成员,我们无法做到这一点。你们的反馈使我们能够更好地确定工作优先级,并在实现目标方面取得进展。感谢你们!
我们将在三个部分介绍本月的工作
- 学习区域:为了确保我们专注于真正对 OCaml 及其社区的成功产生影响的变化,我们针对 OCaml 新手开展了一项用户调查。调查使我们能够更好地了解他们对现有网站的看法,以及他们对未来变化的需求和愿望。
- 包文档:继最近对包区域进行的更改之后,我们继续改进包概述和文档页面的可用性。
- 常规改进:我们还致力于常规维护和改进,并将重点介绍其中的一些。
学习区域
1. 用户调查
本月,我们发布了调查,这项调查从 3 月份就开始准备。该调查在多个平台上推广,包括官方的 OCaml Discuss 平台、Discord、LinkedIn、Twitter,并获得了大量的参与:在我们需要关闭调查以充分分析结果之前,我们总共收到了 57 份回复。
除此之外,我们还回顾了之前关于学习和包区域的用户访谈录音,以便对用户反馈进行分组和优先排序,用于即将开展的用户访谈。我们还在OCaml Discuss 上发布了调查结果的公开摘要。
总的来说,我们现在处于一个非常有利的位置,可以了解应该对学习区域进行哪些更改才能改善 OCaml.org 上的学习体验。我们的工作将在 5 月份继续进行,届时我们将为新的学习区域创建第一个线框图。
2. 文档页面正在进行的改进
除了上面概述的学习区域的高级全面改造之外,我们还在文档方面进行了一些较小的改进,以持续改进文档内容。
许多ocaml/ocaml.org 上未完成的拉取请求包含对学习区域现有文档页面的更新。我们计划在 5 月份合并其中大部分请求。
我们非常感谢您一路提供的反馈、建议和帮助。我们努力通过在 OCaml.org 上提供高质量的内容来使学习 OCaml 变得更加轻松。这是一项相当艰巨的任务,每个人的帮助对于让我们实现这一目标至关重要。
包文档
继最近对包区域进行的更改之后,我们继续改进布局。值得注意的是,我们在学习和包部分添加了一个小的页脚,这解决了在滚动到页脚时粘性侧边栏移出屏幕的问题。为了在滚动浏览文档时更好地突出显示当前活动的部分,我们重新设计了包和学习部分的目录 UI。
现在,当包概述页面上的反向依赖项超过 100 个时,我们会将其折叠。为了为即将推出的包状态徽章腾出空间,我们根据Figma 设计将包区域中的面包屑移到了主内容区域的上方。我们还更新了包搜索结果页面的样式,使其更加紧凑,折叠了包含 5 个以上项目的作者列表,将包标签的样式与包概述页面上的样式保持一致,并添加了一个直接跳转到包文档的链接。
相关 PR/问题
-
学习部分和包部分现在都有一个附加到屏幕底部的页脚 (ocaml/ocaml.org#1018)。这解决了当滚动到页脚时粘性侧边栏向上移出屏幕的用户体验问题。我们探索了一种替代方案,即在页脚进入视野时缩小侧边栏,但最终放弃了这种方案,因为它的复杂性和维护需求更高。
-
包部分以及学习部分的目录 UI 经过重新设计,以便在滚动浏览文档时突出显示当前活动的部分 (ocaml/ocaml.org#1094)。这使得更容易查看阅读进度,也更容易了解我们在较长文档中的位置。
-
包文档部分的布局现在更宽 (ocaml/ocaml.org#1097),在
xl
屏幕尺寸下增加了间隙。 -
由于一个包可能存在数百甚至数千个反向依赖项,因此我们现在在项目超过 100 个时折叠反向依赖项部分 (ocaml/ocaml.org#1101)。
-
包区域中的面包屑现在位于主内容区域的上方 (ocaml/ocaml.org#1133),目的是为包名称旁边腾出空间,用于即将推出的徽章,例如提供有关构建状态的信息。
-
我们更新了包搜索结果页面的样式,使其更加紧凑 (ocaml/ocaml.org#1134):(a) 包含 5 个以上项目的作者列表通过列出前 5 个作者和“等”来折叠,(b) 包标签现在与包概述页面上的样式相同,(c) 提供了一个直接跳转到包文档的链接。
正在进行:基本包内搜索
在上个月,我们在为 OCaml.org 包文档引入基本包内搜索功能方面取得了进展。原型正在staging.ocaml.org上开发(参见此 Discuss 帖子),我们计划在 5 月份推出包内搜索的基本版本。
我们将发布初始版本作为实验版本,因此它可能存在一些问题,并且功能非常有限。我们之所以尽早发布,是因为我们发现包内搜索对于包文档的可用性至关重要。此过程的优势在于,我们能够在以后设计最终产品时适应您的反馈和想法。
常规改进
我们改进了OCaml.org 仪表盘和 GitHub Actions 工作流。仪表盘现在显示 Git 提交哈希值和以字节为单位的内存消耗。我们致力于修复 RSS Feed 抓取工作流,这使得能够通过 GitHub UI 触发抓取程序运行,以及能够在本地机器上运行工作流。抓取工作流在应对来源暂时不可用方面变得更加稳健,并且“博客”页面的各个 Feed 现在是分别抓取并合并到全局 Feed 中。
我们目前正在努力在包概述页面上公开包的构建状态数据。我们还开始与 OCaml 社区合作开发一个专门的 OCaml“安装”页面。新页面将提供有关如何快速设置 OCaml 的更简短说明,相应的补丁包含对“快速入门”文档的全面修订。
除了所有这些之外,团队还勤奋地处理了许多错误修复和提高用户体验的改进。
相关 PR/问题
-
我们改进了ocaml.org 仪表盘,以便显示当前运行实例构建的 Git 提交哈希值 (ocaml/ocaml.org#1136),以及显示以字节为单位的内存消耗 (ocaml/ocaml.org#1060)。为此,构建需要在启用 Git 的文件夹中进行,这需要在部署管道上启用“包含 Git”选项 (ocurrent/ocurrent-deployer#184)。
-
当引入 Git LFS 来存储 OCaml Playground 资产时,RSS Feed 抓取(提供我们在“博客”页面上显示的数据)在 1 月份中断了。我们观察到的另一个问题是对某些来源的 HTTP 请求会超时 (kayceesrk/river#8)。我们致力于修复抓取工作流,并最终取得了成功。由于这项工作,我们现在可以享受 GitHub Actions 工作流的改进,例如能够通过 GitHub UI 触发抓取程序运行,以及能够在本地机器上运行工作流 (ocaml/ocaml.org#1068)。随后,抓取工作流在应对来源暂时不可用方面变得更加稳健 (ocaml/ocaml.org#1120),并且,而不是通过同时抓取所有来源来构建全局 Feed,各个 Feed 现在是分别抓取并合并到全局 Feed 中 (ocaml/ocaml.org#1144)。
-
我们正在努力在包概述页面上公开包的构建状态数据 (ocaml/ocaml.org#977)。作为这项工作的一部分,基础设施团队已将 check.ocamllabs.io 移动到 check.ci.ocaml.org (ocaml/infrastructure#40)。
-
为了提供有关 ocaml/ocaml.org 存储库中使用的编程语言的更佳统计数据,我们现在从统计数据中排除供应商文件 (ocaml/ocaml.org#1074)。
-
一些与 AlpineJS 相关的错误修复和清理,涉及搜索下拉菜单 (ocaml/ocaml.org#1069)和侧边栏 (ocaml/ocaml.org#1061)。
-
将 AlpineJS 升级到 3.12.0,将 HTMX 升级到 1.9.0(解决ocaml/ocaml.org#877)。
-
在OCaml社区(https://discuss.ocaml.org/t/please-improve-my-draft-of-an-install-page-on-ocaml-org/11837)的帮助下,我们开始着手开发OCaml的“安装”页面。此页面的目的是通过利用JavaScript进行操作系统检测,提供快速设置OCaml的简短说明。即将发布的补丁包含对“快速上手”文档的全面修订,以提供更好的章节标题,并澄清说明的同时,减少文档中的冗余内容。
-
针对关于包文档构建失败的询问,CI团队帮助我们调查了该包的求解器为何失败。事实证明,目前,求解器似乎只使用了两个OCaml版本:4.14和5.0.0。在这种情况发生变化之前,任何不兼容这两个OCaml版本的包都将无法成功构建其包文档。
-
一个突出显示OCaml社区之前所有Outreachy实习项目的新页面(ocaml/ocaml.org#1009)已添加到社区部分。
-
我们改进了HACKING.md文档,以提及开发环境的先决条件,并链接到CI构建并存储在Docker Hub上的Docker镜像(ocaml/ocaml.org#1102)。这样做是为了让新贡献者更容易加入项目。
-
添加了“Roboto Mono”作为专用的等宽字体(ocaml/ocaml.org#1085),以确保所有用户都能一致地显示代码段。
-
OCaml用户报告了文档中的错误。感谢!我们立即修复了它们:(1)解决未使用的for循环索引i错误ocaml/ocaml.org#1084,(2)删除对utop的错误提及ocaml/ocaml.org#1086,以及(3)解释如何在
utop-full
中激活-dtypedtreeocaml/ocaml.org#1089 -
我们将一个实验性的YAML解析工具tmattio/yoshi引入到ocaml.org存储库中,以探索这是否是一种简化ocaml.org当前
ood-gen
工具的YAML解析方面的好方法。 -
顶部导航栏中的包自动完成搜索输入现在反应更快,因为已删除节流延迟(ocaml/ocaml.org#1122)。
-
我们致力于实验性的变更日志页面。
-
考虑到我们的Web栈中存在一些未满足的缓存需求(例如,在包文档部分:查看许多HTTP请求并渲染模块树菜单),我们联系了OCaml社区,以了解目前生态系统的情况,以及是否有机会作为我们对OCaml.org工作的组成部分,为OCaml生态系统做出有意义的贡献。
-
有一个开放的PR用于添加WIP开发容器,这可以使开始在ocaml/ocaml.org存储库上进行开发变得更容易。
-
OCaml.org项目通过将其GitHub存储库中添加
CODE_OF_CONDUCT.md
正式采用OCaml行为准则(ocaml/ocaml.org#1135),并通过将ocaml/ocaml.org添加到采用者列表中(ocaml/code-of-conduct#6)。 -
学习区域的练习部分中的问题现在可以按难度进行筛选(ocaml/ocaml.org#1141)。
-
错误修复:练习部分的问题难度符号在过小的边距中会被截断。现在,练习部分的问题难度符号仅在
xl
屏幕尺寸上显示在边距中(ocaml/ocaml.org#1138)。