关于文档,没人告诉你的事
What nobody tells you about documentation
频道:PyCon AU · 时长:30:52 · 发布:2017-08-06 · 播放:105299
简介
Daniele Procida在PyCon AU 2017的演讲提出了一个系统,将文档分为四类,通常画成四个象限。他解释了为什么混合它们会让文档变差,以及分离它们如何改善写作。
HN 为什么推荐
HN推荐它作为对结构化文档实用框架的最佳简明介绍,也是后来Diataxis的基础。
我强烈推荐Daniele Procida关于这个的演讲 — HN, 2021
Python、Ruby 与脚本语言 · 软件实践、开源与职业 · 文学与写作技艺
中文字幕节选
欢迎。嗯,我叫Winnie,我来介绍嗯,Danielle Prasha。他是Django核心开发者。 他在DVIO工作,住在Cardiff,在那里他帮助运营一些活动,比如嗯, PYF、Pyon Namibia和Pyon UK。 他有过各种不同程度的成功,当过高中老师、公司 董事、哲学讲师,还有一些他不愿提及的事情。 但真正成功的是几年前成为一名程序员。 他深度参与了国际Python、Django、开源软件 社区,并对非洲的开源软件开发有特别兴趣。 请大家热烈欢迎Denny [掌声] 非常感谢 嗯,Winnie,也感谢大家来到这里。 嗯,我们有没有,我的设备有问题吗?好了。 好的。所以,我是Danielle Pachida。 这就是我。我希望这能成为我的护照照片,但他们不让, 因为上面写着我是Python软件。 你看。所以嗯,所以呃 简单介绍一下我,嗯,我在DVO工作,一家瑞士的Django 公司。我们为不想做DevOps的Python和Django开发者提供云托管。 所以之后可以来找我聊聊这个。 我是Django核心开发团队的成员,也是Django 软件基金会的董事会成员。正如Winnie提到的,我参与了 Python非洲运动或项目,随便你怎么称呼它。 嗯,我们举办了各种会议、Pyon和社区活动,嗯,开始 于,嗯,我参与的第一个是2015年的Pyon Namibia,昨晚 因为我没有时差,我终于把africa.python.org上线了。 所以如果你去看,你将是世界上除了我之外第一批看到它的人。 所以去看看吧。 这是一个嗯,向世界其他地方介绍非洲Python社区的机会。 也许我们很快会在某个非洲Pyon上见到你们中的一些人。 之后也可以来找我聊聊这个。 嗯,哦,你可以在网上找到我,但最好的是,直接来找我 像正常人一样聊天,因为我最喜欢那样。 嗯,所以大家都知道,更好的文档会让 你的项目更成功,因为你知道,当你嗯,与世界 分享你的软件时,尤其是开源软件,你希望世界 使用它。但许多项目和作者都违背了一个非常简单的原则, 那就是无论你的项目多好, 如果文档不够好,世界会说:“非常感谢。 我要用别的了。” 所以,如果文档不够好或不存在,世界会找到 其他方式来解决它的问题,而认为你的方式 太麻烦了,不值得考虑。 你知道,也许如果你有员工,比如,或者或者手下,或者 至少是助手之类的,那么你可以让他们使用你的 软件。但对于我们这些没有手下或助手的人来说,我们依赖 于人们选择使用嗯软件与否。 即使你能强迫人们使用你的软件,当然,如果你 有唯一的解决方案,或者这些人是你的嗯员工,他们也不会 用得很好,如果文档不够嗯好的话,或者他们不会非常 有效地使用它。现在,大多数人实际上确实尝试创建好的文档。 他们投入了努力,但大多数都失败了。 嗯,这不是因为他们不够努力,或者因为他们不认真
HN 上的讨论
与此相关:理解各种类型的文档,并适当地使用它们。我强烈推荐Daniele Procida关于这个的演讲,[0] 以及 accompanying 网页 [1]。他给出了4种文档的有用分类。通过Unicode的力量: ┌──────────────────────────┬─────────────────────────┐ /\ │ 教程 │ 操作指南 │ || 实践 │ (学习导向) │ (问题导向) │ || ├──────────────────────────┼─────────────────────────┤ │ 讨论 │ 参考 │ || │ (理解导向) │ (信息导向) │ || 理论 └──────────────────────────┴─────────────────────────┘ \/ <=== 对学习有用 对编码有用 ===> [0] [VIDEO] (将带… — MaxBarraclough, 2021-03
____对文章的回应____ 工程师很少擅长撰写技术文档,尤其是与专业的技术文档撰写者(用作者的话说就是“秘书”)相比,后者按定义就应该擅长。工程师的成本通常高于技术文档撰写者。好的技术写作在文档生成期间和之后都能节省工程时间。作者花了大量时间,却拙劣地表达了一个观点:要成为一名优秀的技术文档撰写者,你必须理解谁需要什么以及为什么,然后根据上下文找出最佳解决方式。____生成技术文档的系统____ 任何寻找良好文档生成系统的人都应该看看:[LINK] 其中有一个30分钟的演示:[VIDEO] 关于该系统的先前HN帖子在这里:[LINK] — O__________O, 2022-06
要成为一名优秀的技术文档撰写者,你必须理解谁需要什么以及为什么,然后根据上下文找出最佳解决方式。任何寻找良好文档生成系统的人都应该看看:[LINK] 其中有一个30分钟的演示:[VIDEO] 关于该系统的先前HN帖子在这里:[LINK] — O__________O, 2022-06
这不是一本书,而是一个网站[1]和一个演讲[2],它们基于四个象限解释了编写文档的好策略。[1] [LINK] [2] [VIDEO] — ivan_ah, 2022-03
它们官方上是相关的。个人而言,我更喜欢我使用的链接,因为它提供了目录以及指向这个关于该系统的YouTube演示的链接:[VIDEO] — O__________O, 2022-06
相关视频
- 旋转杠杆 - 变速箱如何工作 (1936) · US Auto Industry · 9:40
- 约束即自由,自由即约束 — Runar Bjarnason · Scala World · 51:39
- 行列式 | 第6章,线性代数的本质 · 3Blue1Brown · 10:03
- Doug McLean | 空气动力学中的常见误解 · Michigan Engineering · 48:25
- Zig:为健壮性、最优性和清晰性而设计的编程语言 – Andrew Kelley · Recurse Center · 54:13
- 特征向量与特征值 | 第14章,线性代数的本质 · 3Blue1Brown · 17:15
- Siggraph2019 几何代数 · Bivector · 1:37:21
- 曝光:埃克森美孚对气候变化立法的游说战 · Channel 4 News · 8:52
- Swami Sarvapriyananda 在 IITK - 根据曼杜基亚奥义书的“我是谁?”- 第一部分 · Vivekananda Samiti, IIT Kanpur · 1:27:07
- Nima Arkani-Hamed:时空的终结 · Max-Planck-Institut für Physik · 49:42
- Ruby Conf 12 - Y Not- 函数式编程历险记 by Jim Weirich · Confreaks · 53:21
- 神经网络和反向传播的详细入门:构建micrograd · Andrej Karpathy · 2:25:52
- Python如何被泄漏的内部机制塑造,Armin Ronacher,Flask框架 · Видео с мероприятий {speach! · 49:55
- RailsConf 2014 - Sandi Metz 谈所有的小细节 · Confreaks · 38:47
- 领导力实验室:有效写作的艺术 · UChicago Social Sciences · 1:21:51
- 事件循环到底是什么?| Philip Roberts | JSConf EU · JSConf · 26:52