要不要写一个Julia学习的Roadmap?

@Jun 希望管理员注意下这个帖子
最近打算把主力语言放在Julia上,是时候走向精通Julia的道路了
然而,好像没有Roadmap可以参考,隔壁 Rust 的roadmap好像做的不错


我们这边还要自己搜索项目实践,大部分人还没有梯子
需不需要改进下文档,参考 Rust 语言圣经 ,制作一个学习Julia的Roadmap,帮助用户更好的掌握和精通Julia
ps: Github上Julia的组织有很多,各司其职,我们把他们的第三方库作为学习材料吧

7 个赞

其实没有必要问要不要。直接开项目就行了。

不过我对现阶段写 roadmap 感到悲观,最佳实践是需要踩坑得到的。踩的坑多了,剩下的路就是最佳实践。
Julia 这边可能还没到这个阶段?或许可以去英文社区问问看法。


我倒是有另外的想法:

首先介绍一下一种文档的组织/分类形式:https://diataxis.fr/

文档可分为四类:

  • 手把手的萌新教程:低背景知识,关注可操作性
    目前来看视频版的手把手教程是最优解。
  • 任务导向的操作指南(How to):需要基本的背景知识,关注如何实现某种功能,给出一套默认的配置。
    经典的操作指南就是:菜谱。(当然我们写操作指南应该更精确、更详细一些)
  • 技术参考文档:需要基本以上的背景知识。详细解释某些参数的含义、API 设计的思路
  • API 参考:大而全的 api doc,一般是自动生成的。

现阶段可能从操作指南入手撰写教程会比较合适。

这样只用关注一个主题,例如:

  • 使用 Documenter.jl 为新包生成文档
  • 本地测试 HTML、PDF 的文档生成
  • 添加 github CI,让 Documenter.jl 自动更新 github pages 并生成 PDF
  • 自定义 PDF 的封面

等到我们的操作指南涵盖的方面多了,并经过了一段时间的检验。
这个时候就可以开始写真正的 roadmap 了,告诉大家什么是最佳实践。


举一个实际的例子:
目前为julia生成完整的 PDF 需要自行编译julia,然后在 docker、或者本地的 LaTeX 环境中编译 tex 文件,生成 PDF。

本地编译 julia 就比较麻烦,后面生成了 tex 文件,编译为 PDF 则耗时冗长。
主要的问题在于两点:

  • 生成文档依赖特定版本的 stdlib。不过如果你用 release 版本其实不需要自行编译
  • 构建 PDF 缓慢则是因为:代码高亮过程需要调用外部python程序,而这个过程是串行的。所以非常慢。
    但你可以开启 draft 草稿模式,这样基本只需要1~2分钟就能得到 PDF,而默认的配置需要数十分钟。

我有这两点经验,但并没有合适的方式写出来。

Viral 说可以把第二点加到文档里。但我感觉并不太适合,我把第二点当作一个 bug,或者至少是个 issue,我的一点经验算是 workaround 不适合放在文档里。

It would be nice to add the PDF building tips to Documenter’s docs.

Originally posted by @ViralBShah in https://github.com/JuliaDocs/Documenter.jl/issues/1785#issuecomment-1088727337

其实这种就适合于写一篇操作指南:“快速编译预览 PDF 版 Julia 文档”

2 个赞

我觉得这种 project-based 也可以参考
https://github.com/practical-tutorials/project-based-learning

之前有社区的小伙伴提到 Julia 语言入门指引 - #18,来自 why7682 太过时了,也许可以考虑对它进行一个重写

重写就做成一个新项目吧,不然那个帖子只有原作者和论坛版主才能修改。

要不我有空新发一个帖子把,管理员能不能帮我置顶一下 :wink:

1 个赞

必然的,发帖之前也可以通过 hackmd.io 来共同编辑

  1. 我觉得原来的入门指引确实需要更新,而且可以考虑在julia英文官网的学习页的基础上,加点儿中文资源的备注和链接,放到julia中文官网的学习页里。

  2. 至于rust,

  • 了解了一下,我不知道rust的学习曲线是怎样的,rust有官方文档、通过例子学习、通过练习学习,等等好几个版本的学习资源。而圣经指的就是《通过练习学rust》,是在通过例子学rust的基础上改的,改进的思路包括扩写、习题而不仅仅是例题、难度分级等,其目的旨在架设从入门语言到上手真实项目的桥梁,恐怕最关键的地方是有中文的翻译版本,而且翻译后的名字变成了“rust圣经”。

  • 《通过练习学rust》这个项目,说的是架桥到真实项目,真的就是桥,不包含真实项目,我随便翻了几页,发现就是将文档习题化了而已。这个项目仍在施工当中…

  • 除了rust,其实有更多的python、c、java的例子可以借鉴,由于可借鉴的东西太多,而且不同语言学习曲线和功能特点不同,所以问题的关键是明确定位,这个帖子究竟想要什么?如果只是希望通过例题习题学习文档,julia已经有了一些资源,见 3.

  1. julia至少有两个资源接近楼主所需,都在julia官网的学习页里:
    1.中文版的julia wikibook(例题化的文档)
    2.英语的julia exercism(习题化的文档)

julia wikibook的中文介绍说得挺好:


总结:

  • 更新入门指南
  • 更新中文官网,尤其是学习页
  • 看 julia exercism or wikibook(cn)
  • 由于没有中文翻译等原因不满意现有学习资源,写资源
4 个赞

如果有人有具体实施计划和大纲,并且愿意带头做这样一个工作的话,JuliaCN 可以考虑从去年 OSPP 导师捐赠的奖金中拿出一部分来赞助这件事情。如果想要一个更长时间和更大规模工作量的项目的话,也可以依托于今年的 OSPP 开源之夏项目去做。

1 个赞

关于 roadmap 这件事情我周末在 JuliaCN 邮件组里组织了一次投票确认。大概的一个赞助策略是:做到 Welcome - Julia Data Science 相似程度的工作,根据进展可以给予 3000 元左右的资金。

另外今年有一个 OSPP 的项目名额暂时没有计划,也希望能够留给文档类工作,比如说:用 Julia 进行数学建模(比赛)相关的内容,一些好的生态文档的翻译,中文主页的更新,等等。今年的项目资金调整为 8000 元。如果有合适的周期为两个月左右的项目计划请在 5月5日 之前联系我。因为涉及到 OSPP 名额的划分,所以如果有意向就可以提前联系。

联系方式可以私信或者邮箱 johnnychen94@hotmail.com

英文论坛最近的热帖里讨论到了如何改进主文档。有兴趣可的可以去看看。
(主贴是关于 julia 的吐槽,并且歪楼的不少,而且很长)

基本的共识是,R, python、MATLAB 的文档写的好,值得学习。
然后就讨论如何改进 julia 的文档。
总的来说大家还是期望做一些小修小补。

  • REPL 内更好的文档搜索、基于参数类型的筛选
  • 改进错误信息(单独的话题、略)
  • 增加更多连接
  • 更多示例,例如给 sin 加上绘图示例。(这里有一些争论,选哪个绘图包作为默认的?)
  • 在示例中重复推荐的基本代码片段,让用户潜移默化的的学习

里面也有人提到了 https://diataxis.fr/ 的文档分类法。和一些对文档结构改进的想法:

  • 针对不同的背景知识水平推荐不同的学习内容
  • 学习 MATLAB 每个函数单独作为一页
  • 为 docstring 增加更多内容(我理解为把更多内容从单独的文档加入 docstr 中,python 是这么干的)。如:导入 wikidata 的说明、添加图像

我是比较支持对文档的结构进行一些调整的。
julia 的文档目前把不同类型的文档混在一起:新手教程(只有一点点)、HOW-TO(大部分文字介于 how-to 和教程之间)、API 文档(stdlib 和一部分 base)、设计说明(devdoc)

python 的参考文档与 docstring 基本是等价的。
但 python 会有单独的 HOW-TO,其他的标准库示例教程,甚至 PEP 提案自带不少例子,也可以作为一种文档。

也有开新项目协调文档改进的:

3 个赞

另一方面我对于中文主页的现状其实也是不太满意的… fork 英文主页总感觉不如在主页的重要部分贴上英文主页的链接。

英文社区的一些新(旧)想法

文档下评论一个可能更方便的选项是gitalk

备案号:京ICP备17009874号-2