2022W22 - 首次周报尝试
2022-06-06 23:07:58

上周末读了 Xuanwo 大佬的博客,开始想要也写一份公开的周报,总结工作和学习。或许通过公开自己的学习进度,能逼我每天学点东西。

GitHub Projects

Again,受到 Xuanwo 的启发,尝试用 GitHub Projects 来追踪我的工作。由于 P 社的内部工作有很多依赖于 Jira,并不是所有事项都有对应的 GitHub issues,而我单独为自己开个 issue 又显得有一些怪异(为了追踪而追踪?),所以目前看来只能追踪一部分有公开 issue 和 PR 的事项。先尝试一个 Iteration 看看。

API 文档

这周大部分的业余时间花在了研究 API 文档上。学习了 Redoc 的工具链,开源版基本可以实现大部分我想要的功能。

  • 把较大的 OpenAPI 定义文件拆分成多个小 YAML,降低手写 YAML 的复杂程度。
  • 支持把小 YAML 重新 bundle 成一个大的 YAML 文件。
  • lint OpenAPI 定义,支持自定义规则。
  • 渲染 API 参考文档。
  • 自定义主题。

在选型的时候偏向于 Redoc 而不是 Swagger UI 的原因有两个:

  • 我喜欢 Redoc 的 three-panel design (Demo),不太喜欢 Swagger UI 的设计 (Demo),尤其是 model 部分,总感觉很局促。
  • Swagger UI 的风格和 P 社文档不太搭。

周末大致跑通了从编写一个 endpoint 的 openapi.yaml 到渲染文档的整个流程,包括怎么拆分和 bundle 不同的 YAML 文件、把 conceptual docs 和 reference 组合在一起、添加 code sample、给资源分组打 tag 等。接下来要做的事就是和前端一起看看源文件的更新和维护流程。

Code 文档

读了一部分 VIII: Code tutorials,主要讲了 Documenting Code。我几乎没有给长篇的 code sample 写过文档,想了想还是挺有意思的。

根据 2021 State of API report by SmartBear 这份报告,受访者最想要的文档内容是 “Example”,其次是状态码和认证。对开发者来说,API 文档中最重要的元素就是 code sample。在文档中添加可用的 code sample,方便开发者直接复制粘贴,是提高开发者体验的重要一环。

但对 technical writer 而言,给代码写文档有很多挑战:

  • 代码是非线性的,不遵循 step-by-step 的范式,这和 technical writer 习惯的 Task-based procedure 不同。
  • 读者的技术水平相差较大。由于读者的技术水平不确定,文档可能写太多——对资深开发者太细碎,也可能写得太少——对初级开发者太晦涩。
  • 需要理解特定的编程语言。technical writer 不一定了解目标编程语言,即使有所了解,ta 需要写的对象通常是较为复杂的 (“simple code might not need documentation at all”)。
  • 需要保证在版本迭代后代码仍然适用。有较高的维护成本,例如经常需要测试代码可用性。
  • 工程师有对代码的审美。工程师能辨别什么是好的代码,什么是糟糕的代码,但 TW 不能。

Hexo

想到要公开写周报,又从头熟悉了一遍 Hexo,给博客换上了 oranges 主题。Hexo 真的很好上手(。

之前的部署方案是在 source 分支上放源文件,用一个 GitHub Action 来 build 并 push 到 master 分支。但是这样我的 draft 文件也会被推到公开的 GitHub repo 里,不太喜欢(因为我会在 draft 里讲很多 B 话,在 publish 之前删掉它们)。

这周读了 Hexo 的文档,发现了 One-Command Deployment,一行命令部署到 GitHub Pages:

1
hexo clean && hexo deploy

我好懒,这个最适合我了。

乐理

这周学了一些拍号的知识。拍号决定了音乐的律动,也即音乐的强弱关系

  • 无论什么拍号,每个小节的第一拍都是强拍。每个小节只有一个强拍。
  • 强拍的音量不一定响,弱拍的音量不一定弱。

拍号可以简单分为三类:

  • 单拍子:每小节只有一个强拍,并且也存在弱拍。例如 $\frac{2}{4}$ $\frac{3}{8}$
  • 复拍子:由相同的单拍子组合起来的。例如 $\frac{4}{4}$ $\frac{6}{8}$
  • 混合拍子:由不同的单拍子组合起来的。例如 $\frac{5}{4}$ = $\frac{2}{4}$ + $\frac{3}{4}$。 混合拍子的强弱关系会有不同的可能,实际情况中要结合旋律、和声织体、节奏等因素去判断。

如果某个拍号由多个拍号组合而成,那么每小节的第二个强拍开始,都要变成次强拍。

我现在最熟悉的是 $\frac{4}{4}$ 拍,我擅长的节奏型大多适合演奏这个拍号,比如民谣扫弦、民谣分解。

总结

第一次公开周报,ドキドキしている。

下周想继续学 API 文档,了解怎么从 Proto buffer 生成 YAML,看一看 Simplified Technical English,有时间的话再接着看一点 Google Analytics advanced course。