/tags/misc/ Recent content in misc on Hugo -- gohugo.io en Wed, 31 Jul 2024 00:00:00 +0800 /posts/process/ Wed, 31 Jul 2024 00:00:00 +0800 /posts/process/ 作为内部开发平台的开发者，文档的写作流程和自己写博客也是不同的。 Scoping and requirements gathering 在公司或项目种，文档需求可能来自各种内部和外部来源，包括以下几种情况 正在进行的新功能，可能来自产品负责人 已经完成的新功能需要文档 由你自己或者其他记录的问题 在开始补充这些文档内容的时候，第一步是要弄清楚当前“完成”的定义。不同人对其有不同的看法。尽管你可能已经尽力而为了，你仍然可能发现你对“完成”的理解和实际情况不符。 根据你合作的人和你所在的公司或项目类型，你可能需要采取不同的措施来减少这种情况的发生。 首先，询问stakehoders，他们对内容的预期是什么 产品负责人可能希望你描述新功能如何帮助用户解决问题。 一位工程师可能希望你描述功能的具体细节，比如组件是否有本地缓存，是否支持动态变更， QPS能能够达到多少。 需要站在stakeholders的角度，了解他们的意图，很多时候并不是简单的事情。 What to document 任何工作开始之前都有个工作量评估，你可能会想要知道要做什么以及需要多少文档。 文档是个迭代的过程，尤其是当你是一个小团队（没有足够人力和时间）或者作为另一项工作的一部分来完成文档的时候。 几乎不可能一次性记录下产品可能需要的所有内容。（我不知道有没有人能在项目过程中记录下所有细节并在最后的文档中体现，但我知道这些都需要时间。） 除非你在的某些行业，要求在发布时必须有完整且准确的文档，例如医疗、敏感工业等，否则不太可能需要一次性记录所有内容。 应该怎么开始，怎么推进呢？ 推荐的是从头开始，然后是结尾，随着时间的推移，基于反馈慢慢填补中间的空白。 这意味着 首先创建一个或两个getting started guide，然后确保提供reference documentation可以覆盖API或者SDK函数。 当都准备好后，你就可以发布"minimum viable documentation"。 这些getting started guides对想体验产品的人来说要足够可以衡量是否满足他们的需求。 reference doc要足够让知道自己要做什么的人获得要使用的组件的足够细节。 在这些内容到位后，你可以利用product roadmap，在后续排期中，进一步完善文档。 Draft 与其他任何形式的写作类似，一稿往往是不够的。一旦你有了初稿，你需要让所有相关的stakeholders查看并给出意见。 这个过程可能需要一些时间，但对于确保准确性的项目来说，可能是必要的成本。 在文档上获得多轮反馈可能与你的期望和假设能力直接相关。如果这些在早期阶段不清楚，那么很可能在反馈过程种会显现出来。有时，这是因为你误解或错误地假设了与你沟通的内容。更常见的是，因为人们往往不确定自己的想法，直到看到你具体产出的文档，才直到差异。所以在文档上也需要快速原型，不要在细节上一开始就纠缠太久，细节都可以在后续完善。 文档反馈通常有两种极端： 几乎没有反馈，以至于你不确定任何人的想法 或者有太多反馈，你不知道从哪里开始。 、 如果你没有收到足够反馈，你可能需要安排特定的会议从stakeholders那里获得反馈。当面对大量的文本或修改列表时，人们可能有些无所适从，所以你需要问具体的问题。 太多的反馈并不一定意味着你做得不好。一些Reviweer很有主见，或者有许多想法要分享。 处理太多反馈的困难在于筛选出有用的部分，并决定如何处理 有用的，记下来，未来再安排时间处理，并礼貌地感谢reviewer的comment。 不需要的，以友好，专业的方式推回反馈，并解释不接受的原因。(counter-feedback) 有时候，对特定问题反复纠缠会让人变得烦躁甚至关系变得紧张, 特别是以书面的方式，异步地表达的时候。我们应该都碰到过这种情况：对话和讨论变得紧张、具有攻击性、琐碎。所以交流的语言尽量是包容性的。 不经太多思考，快速写出第一个版本很可能是有很多问题的，但这样做，可能将排接压力、误解、最终还可能节省时间。 在处理在线交流的时候尽可能务实、耐心和开放，才可以保持对话的礼貌和富有成效。 那么，什么时候反馈可以完成，并发布文档更改呢？ 大多数项目可以在后续过程种不断迭代。通常在外部压力下，会设定一个发布时间，在期限内需要结束反馈并发布。 Feedback 用户可以通过gitlab/github issue提出feedback。当然有些团队也通过调查问卷的方式进行。 公共反馈所见到有用的部分需要筛选 某些虽然有效，但影响人数太少，可能不值得处理 有些人认为的问题，可能实际上并不是问题，而是因为背景知识的缺失或其他原因造成的。 内部路线图、优先事项和预定排期可能会优于外部反馈和请求。但这并不意味着你可以忽略外部输入，可能还是需要和反馈者沟通。 Metrics and measuring success 我们有收集一些metrics来评估文档的效果。比如收集文档页面的访问量，停留时间等。追踪用户是如何浏览页面的，可以知道哪些文档需要重点维护，哪些使用率很低，是否需要提高。 /posts/different-doc-types/ Tue, 30 Jul 2024 00:00:00 +0800 /posts/different-doc-types/ Shoppe的工作主要是给内部开发者提供开发工具或者说开发平台，帮他们使用内部的标准化开发流程，提升开发效率和开发体验。这份工作和我以前的工作经验最大的区别是面对的用户是内部开发者。 面对大量的内部用户，所有问题一一探讨是不可能的。此时文档就是个很重要的交付件，好的文档能减少大量的交互成本。 科技写作并不是我擅长的，所以我在这份工作中也学习了很多。 Gas是一个基于Go的应用开发框架，集成了内部的统一sdk和一些基础服务，比如日志、监控、配置、CICD等。思想类似faas，业务项目的开发者只需要关注业务逻辑，并使用统一的sdk进行开发，后续非业务功能的集成和升级都通过框架来实现。 在基础功能都基本完成后，就需要接入种子用户了。这时就需要文档了。 文档的用户是谁 虽然文档的用户是开发者，但是我们没法保证他们都是非常专业，有些对golang技术栈或者内部的技术栈有些可能都不是很熟悉。所以文档的目标是让用户能够快速上手，而不是让用户能够深入了解。 Learn by example 提供demo是快速上手的有效方式。 从最简单的例子开始，让用户能够快速上手。比如一个最简单的http server，一个最简单的rpc server。 然后就是项目的部署。这样一个完整的流程就有了。 开发过程中有许多细节，都可以编写最简单的用例版本。后续的迭代中填充，比如如何使用日志，如何使用监控，如何使用配置中心，如何使用各种中间件，如何配置CICD等。 在快速发布之后，会收到来自用户的反馈，根据用户的反馈不断完善文档。可以根据反馈问题的影响程度和用户的反馈情况来排定优先级。在开始的阶段，很可能不仅是文档的问题，还有产品的问题，可能需要的修改代码甚至设计。 文档类型 整个项目的文档主要分为以下几类： Getting Started or onboarding Tutorials Reference FAQ Getting Started Getting Started是面向新用户的，目的是让用户快速上手体验，而不是让用户深入了解。 在简单的例子中，无法覆盖所有的细节。必要的说明可以简单提及并给出链接让想要深入了解的人可以继续学习。 常常可能出现的提供太多细节，而模糊了焦点；或者例子太过复杂，让用户无法理解，望而却步。 Tutorials 有时候也被称为how-tos或者guides。一般是Getting Started的下一步。 如果你的产品或者项目可以区分模块或者子项目，需要tutorial sections。 Gas除了服务的engine, 还有集成其他基础模块的子项目，如db, mq, cache等。每个子项目都在自己的repo中，都有对应的ic来完成各自的markdown tutorial。通过SSG(Static Site Generator)来整合所有repo的tutorial。 常见的Tutorials的组织方式有两种，一种是按照功能来组织，一种是按照用例。 按照功能： 从内部开发者的视角说明 What something does, 比如config sdk提供哪些功能，如何使用。 按照用例： 从外部用户的视角说明 What someone wants to do with it, 比如服务的不同regions，有不同的配置，该怎么使用config sdk来完成。 除非应用一开始就是为了特定目的构建的，否则我们很可能是不清楚实际的用例的。所以一开始我们可以按照功能来组织tutorials。随着时间的推移，我们会收到足够的用户反馈，然后再添加各种用例场景的tutorial。 务实地说，我们知道要满足所有人的需求几乎是不可能的。大多数人对文档总会有些意见，因为它无法回答每个人具体的问题和用例。这并不是说不应该努力去满足和超越人们的期望——我的观点是，这一切都需要时间。 Reference 该部分包含了技术细节，每个单独的组件，函数、或者API具体都是怎么样的。 它和前面两种类型的文档的区别是 getting started或者tutorials告诉你怎样使用 reference告诉你使用的各种参数和细节 比如， 在tutorials中你知道怎么使用config sdk，但你无法知道sdk的所有配置参数，这些需要在reference中了解。 /posts/network-issues-about-microk8s-on-my-vps/ Mon, 29 Jul 2024 00:00:00 +0800 /posts/network-issues-about-microk8s-on-my-vps/ Background My homelab is a cluster of 2 nodes.It works well. And I have 3 vps(2 oracle free tier arm, 1 other) and want to set up a new microk8s cluster. But I encouter some network issues. The ingress can’t forward traffic to other pods. It doesn’t happen on my homelab. Solution I keep only one node in the cluster and check the network. kubectl create deployment pingtest --image=busybox --replicas=2 -- sleep infinity kubectl get pods -o wide NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES pingtest-6fd7cf8988-ms5m5 1/1 Running 0 19h 10.