一些功能与内容方面的建议

近期在 rCore-Tutorial-Book-v3 的知识海洋中徜徉，收获颇丰。感谢各位作者的辛勤付出，目前就阅读体验而言给出几点建议：

目前 utterance 评论一旦内容过多，则在相应章节所占页面高度比例超过 1/3 ，已经对阅读体验有所影响，尽管在侧边栏 Sidebar 中已经提供了 TOC, 但该部件在 iPad 等平板阅读设备中是隐藏的，想要翻页则不得不下滑到页面底部或者打开左侧的导航栏，体验并不是很流畅。目前想到的可能的改进思路是使用带 Collapse 或 Dropdown 功能的 Sphinx 样式插件（如 Sphinx Design / Sphinx Collapse），或使用原始的 HTML 语法，默认将评论区隐藏。
GitHub 不久前开放了 Discussion 的 API, 对于 Issue 和 Discussion, 本人更倾向于将更多作为讨论性质的内容放在文档页面底部，而关于项目本身的 Issue 和 Feature Request 等等类型，似乎无在 Issue 中展示之必要。另 Discussion 功能能够方便管理员对一些内容进行更好的分区与管理，例如将一些过时的讨论（比如相关讨论部分由于文档更新已经不再出现在相应章节，或内容已经进行大幅修改，致使其他读者在参考时摸不着头脑）权重降低或转移板块。相应第三方插件有 Giscus. 能直观看到的好处是：能直接在楼层中看到对应的回复，而传统的 Issue 需要 @id + > 的形式，定位起来是较为困难的。
不知贵组目前如何解决 rCore-Tutorial-Book-v3 与 rCore-Tutorial-v3 的版本控制与内容同步问题？例如 RustSBI 中一些接口已转为 Legay 封装，在文档中展示的用法并不同步，如使用 RustSBI 提供的服务一节，与 https://github.com/rcore-os/rCore-Tutorial-v3/blob/d88cd38d69502180b6d880f1c9dea96893d54819/os/src/sbi.rs#L1 所展示的内容已有差异，致使读者不清楚何处为最佳实践；若要同步，又引入了很高的维护成本。这也是为何大部分项目习惯将文档放在自身的 docs/ 下而不做单独分离的原因，MegEngine 文档是通过严格控制 Release 版本号的一致性来保证文档内容的对应。
最后一点是关乎写作的讨论，很高兴能看到国内有如此用心的教学内容产物，但在阅读过程中也发现了几点异样感，这些感觉与我曾经写出 MegEngine 文档得到的用户反馈较为类似，随着作者们投入心力的增加与内容的增多，一个项目中难免出现画风差异，不妨也用软件工程的角度来思考如何维护一个规模日渐膨胀的文档，故也给出一些参考经验，核心想法可在 MegEngine 文档风格指南窥得，rCore-Tutorial-Book 出现纯文字篇幅较长之章节时，读者的阅读欲望便大大降低，关键在于阅读大批干货的过程中注意力容易难以控制的流失，需有合理的组织之法... 若为翻转课堂教学服务，可能需要适时地插入视频等其它直观性、交互式更强的内容；版本维护时，或采取类似 UCB CS61a Denero老师的材料组织思路，他会将课程的知识点拆分成多个单元的介绍视频（Video，基本上不超过 10 分钟），在每个学期将这些视频组织成对应 Lecture 的播放列表，如果新学期引入了新的知识内容就额外录制，否则就用旧学期已经录制好的版本。毕竟完整的课程录像略显啰嗦，而每学期重新录制 MOOCs 视频又不大现实。

悄悄说一句，感觉 Sphinx 用久了就会对它又爱又恨，感觉贵课发展到一定阶段和形态后，一定会有自己的课程网站。

Refs:

你好，非常感谢你能够喜欢我们的项目并给出如此建设性的意见！ 1.关于评论插件：其实我对前端一窍不通，当时搞这个评论插件的时候也是随便捡了一个来用，能工作就没再管它了。如今看来确实已经有了不少弊端，一些评论比较多的页面有效信息基本已经被冲掉了，留在上面的都是一些过时信息。看来更换成能够更加灵活控制的其他插件是个好主意，我有空研究一下Giscus插件吧。 2.关于SBI相关内容代码与文档不同步问题：这个问题其实已经遗留很长时间了。看了tutorial of tutorial之后我意识到这个的确会对学习者的体验造成很大影响，需要放在最高优先级来修掉。至于代码和文档的版本匹配问题，目前这个项目相当于只有最新版本这一个版本，所以也没有考虑版本管理的事情。代码和文档放在同一个仓库后面可能会尝试一下吧。 3.我已经在996搬砖了（悲），感觉只有我自己的话，确实是有心无力。可能得找更多感兴趣的同志来一起帮忙搞一下~至于跟课程结合的话，据我了解这本书在我系os课的定位是类似于ostep参考书，至少前两年课还是正常上的，内容基本按照这本书来走，应该并非翻转课堂的形式。我十分认同在冗长的文字描述中需要有点什么来吸引读者的注意力，成本比较低的可能就是让读者动手操作、例子、插图，但即使这几项看起来做的也不够好，尤其后面几个章节插图的确是太少了。本书有大量的代码实现讲解环节，虽然已经尽量进行了步骤拆解，但看上去还是相当无聊，这个暂时没有想到什么好办法，可能将暂时不需要深入的部分折叠起来分层展示会好一点？视频是一种不错的形式，不过准备+录制会有点麻烦...对于目前状况来说成本有点高。在教程撰写方面，我是尽量站在初学者的视角，从所有相关内容中抽取并构建清晰的逻辑链条地来循序渐进地展示相关知识和项目实现。我有做过很多这方面的努力，希望最终的效果还可以。不过，确实有的时候也引入了一些不必要的背景知识，这些应该排查一下用链接替换掉。 4.其实还有很多特性没做，比如目前甚至还不支持多核，这个我觉得为了对标xv6一定要有的。以及参加工作之后，又学到了很多新东西都可以加入到这个项目中来。闲暇时我也有一部分精力在冥想这些事情，再加上摸鱼，就显得项目很长时间没动来着（实际上确实基本没动）。不过最近工作也确实很忙，我尽量多投入一些吧。

遇到了和柴曾经在维护教程项目几乎一样的创作困境，维护此类项目前期的冲劲是最足的，在学生时期只需要获得导师的首肯和非常少量的资源支持，就能够以及其自由的发挥将项目初版给“糙”出来，但过足够长一段时间后去看此类内容，忽然就会有一种“旁观者清”的视角发现其中诸多的改进点甚至是弊端，虽然最后铆足了劲想要把它变得更好，可现实世界的各种复杂因素会带来各种阻碍，以下是我的一些主观经验补充：

如你所言，工作后的成年人其实属于自己的自由时间是被极度缩减的，而一个人的力量是有限的；
进入社会后，对于这些仅剩的有限的时间，我们又不得不开始进行功利性地考究如何利用它们（除非你已经达到了财富自由的地步），可能会有很多因素会让你选择放弃对原有项目的关注，光靠热血很难得到一个于大家而言都好的结果；
就目前的质量来说，我冒昧地做一个猜测，此项目在贵系作为辅助材料作为课程的试点运行，在最初几个学期可能会由于自身的变化带来一些良好的反馈，但一定会有人吐槽通过实践加深理论认知的方法并非惟 rCore Tutorial 这一种，对于只想快速掌握专业课核心概念的人，这样的循序渐进+实践为主的材料从某种意义上反而是一种负担，任课教师需要考虑到不同水平和需求的学生反馈。rCore Tutorial 如果想要发展成更加通用且质量更佳的 OS 必备材料，必须经过经年累月的积累，我只觉得获得终身教授的人能有魄力做这样的事情。对于负责任的教育领域相关贡献者，最害怕的反而是写出一些误人子弟的东西，这也是为什么学生时期的我们更热衷于去写教程分享自己的知识，而等我们的学识进阶到一定的水平后，却会因为爱惜自己的羽翼不愿去大胆尝试新的创作了（这里指的是对教育有高尚追求的人，如果是写教材凭指标评职称的话不属于此类），说多错多，更何况是这种文字类型的材料，谬误之处可能是非常多的。等我们真正抵达所谓的通透境界，能够把领域知识给三岁小孩讲透之后，却发现自己的时间愈发不够用了...

以上都是一些心路历程，后面还有一些建议。如果这个项目后续的维护人只剩下你一个，我会希望你优先考虑自己的近期发展和仔细想想这个项目投入产出的各种可能，虽然我们都知道大方向上如何让事情变得更好（插图、视频、交互等等），但一个人跑得快，一群人才能跑得远，有的时候燃烧自己维护一个难以预估未来发展的项目是很不可取的，我只建议那些衣食无忧的大家作此考虑。可能苦心坚持多年后会觉得，自己当年如果不在一棵树上吊死，而是让它及时地“死”掉，或许还会有全新发展的可能。

不妨与贵系的任课老师坦诚交流，交换彼此对 rCore Tutorial 项目和 OS 课程教学的看法和期待，任何事情都是存在利益关系的，比如贵系可以借自身的影响力帮你获取更多的项目反馈，但也难免担忧项目质量和后续能否支撑起课程教学的全部，以及对于部分学生来说此类材料是否是妥当的，项目受到的关注越多，责任就愈发重大，甚至即使你毕业后不少人也会认为 rCore Tutorial 和 rCore Tutorial Book 是清华 OS 教学水平的代表（就好像现在提到南京大学的 OS 就离不开蒋炎岩和余子濠两位神人，余子濠的博士毕业答辩你可以看看，想一想十年磨一剑这个概念）。于你而言目前最大的困境可能就是心有余而力不足，当前阶段不要寄希望于开源社区能有人来长期维护，不现实。如何获取资源和支持来保证项目能否走得更远，也是个人能力与发展规划的一部分。事情就变得复杂起来了，倘若你是一名初到实验室的萌新，有什么样的条件会使得你愿意去帮助师兄维护之前他写的一个教程呢（做这件事情能帮我发论文吗？有利于毕业吗？能写进简历吗？）这都是一些很现实的问题，要找到纯粹的人很少，所以更多时候是要凭借利害关系（或者是画饼...）来获得更多的合伙人和支持者。

最后我很感谢你能花精力在这个项目上，但我的本意绝不是逼迫你去产生这样的想法：

不过最近工作也确实很忙，我尽量多投入一些吧。

诚然，自私地讲，如果作者用自己的大量业余时间去维护这样的项目，来满足我和其他人对相关知识的获取需求，作者付出的时间精力和结局我可以是全然不在乎的，我完全可以只在意这个项目能不能帮我学到东西而不顾作者是不是吃得起饭，因为这样满腔热血的 Nerd 真的很难找。但作为半个同类，我会建议你想清楚、规划好再行动，转过头想想，是不是优先发展自己，让自己能达到一个能获取更多资源的位置，再来做一件事情能做得更好呢？如果因为这一个项目投入过多，影响到自己的生活和工作，反而是得不偿失的，莫要让不明此中辛酸的人认为作者是在孤芳自赏和怨天尤人了。

一些题外话，一定要避免由于自己的责任心与现实中的事件冲突从而产生了情绪上的自责，这不是无能、无力、无知，大不了这个东西就摆烂不做了，如果不小心陷入情绪怪圈，很容易让人变得抑郁，恶性循环。建议把目光放在现实生活中更加可爱的事情上，精力充沛地做事情更高效~

P.S: 我甚至不反对你通过和老师合著一本 rCore 书并出版的形式来获取经济来源和创作动力，如果有国家经费支持那自然是最好的了。至于录制视频，其实也有一定的学习成本，不注重视频细节的话可能吃力不讨好，对非学生来说试错成本太高了。

关于评论插件：其实我对前端一窍不通，当时搞这个评论插件的时候也是随便捡了一个来用，能工作就没再管它了。如今看来确实已经有了不少弊端，一些评论比较多的页面有效信息基本已经被冲掉了，留在上面的都是一些过时信息。看来更换成能够更加灵活控制的其他插件是个好主意，我有空研究一下Giscus插件吧。

阅读 Sphinx 项目 Templating 一节，参考其它 Sphinx 主题相关文件的组织，如 pydata-sphinx-theme 会有所帮助，无需学习过多前端知识。

.关于SBI相关内容代码与文档不同步问题：这个问题其实已经遗留很长时间了。看了tutorial of tutorial之后我意识到这个的确会对学习者的体验造成很大影响，需要放在最高优先级来修掉。至于代码和文档的版本匹配问题，目前这个项目相当于只有最新版本这一个版本，所以也没有考虑版本管理的事情。代码和文档放在同一个仓库后面可能会尝试一下吧。

感觉得找到一个更好的工作流阿，可能可以借助 GitHub Action 的 Workflow 脚本自动定时完成 git rebase git am git cherry-pick 等功能，让所有的分支拥有统一的历史主线，但感觉这样的维护对单个人来说还是麻烦

rcore-os / rCore-Tutorial-Book-v3

一些功能与内容方面的建议 #201