@Jun 希望管理员注意下这个帖子
最近打算把主力语言放在Julia上，是时候走向精通Julia的道路了
然而，好像没有Roadmap可以参考，隔壁 Rust 的roadmap好像做的不错
我们这边还要自己搜索项目实践，大部分人还没有梯子
需不需要改进下文档，参考 Rust 语言圣经 ，制作一个学习Julia的Roadmap，帮助用户更好的掌握和精通Julia
ps: Github上Julia的组织有很多，各司其职，我们把他们的第三方库作为学习材料吧
我们这边还要自己搜索项目实践，大部分人还没有梯子
需不需要改进下文档，参考 Rust 语言圣经 ，制作一个学习Julia的Roadmap，帮助用户更好的掌握和精通Julia
ps: Github上Julia的组织有很多，各司其职，我们把他们的第三方库作为学习材料吧
6 个赞
其实没有必要问要不要。直接开项目就行了。
不过我对现阶段写 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
@ViralBShahin [LaTexWriter] Better spacing between section number and title by ViralBShah · Pull Request #1785 · JuliaDocs/Documenter.jl · GitHub
其实这种就适合于写一篇操作指南：“快速编译预览 PDF 版 Julia 文档”
2 个赞
我觉得这种 project-based 也可以参考
重写就做成一个新项目吧，不然那个帖子只有原作者和论坛版主才能修改。
要不我有空新发一个帖子把，管理员能不能帮我置顶一下 
1 个赞
-
我觉得原来的入门指引确实需要更新，而且可以考虑在julia英文官网的学习页的基础上，加点儿中文资源的备注和链接，放到julia中文官网的学习页里。
-
至于rust，
-
了解了一下，我不知道rust的学习曲线是怎样的，rust有官方文档、通过例子学习、通过练习学习，等等好几个版本的学习资源。而圣经指的就是《通过练习学rust》，是在通过例子学rust的基础上改的，改进的思路包括扩写、习题而不仅仅是例题、难度分级等，其目的旨在架设从入门语言到上手真实项目的桥梁，恐怕最关键的地方是有中文的翻译版本，而且翻译后的名字变成了“rust圣经”。
-
《通过练习学rust》这个项目，说的是架桥到真实项目，真的就是桥，不包含真实项目，我随便翻了几页，发现就是将文档习题化了而已。这个项目仍在施工当中…
-
除了rust，其实有更多的python、c、java的例子可以借鉴，由于可借鉴的东西太多，而且不同语言学习曲线和功能特点不同，所以问题的关键是明确定位，这个帖子究竟想要什么？如果只是希望通过例题习题学习文档，julia已经有了一些资源，见 3.
- 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 英文主页总感觉不如在主页的重要部分贴上英文主页的链接。
英文社区的一些新（旧）想法
- 允许在文档下面评论
技术上没有困难，直接 GitHub issues as comments。这样唯一的门槛是拥有一个 github 账号。 - 更好的索引：IBM: Keyword In Context
https://apps.dtic.mil/sti/pdfs/AD0443912.pdf - 对文档贡献者的激励
- julia 可组合性带来的文档编写问题
编写 HOW-TO 只能演示一部分用法 - 背景知识列表
陈老师如果对数学优化包JuMP的官方教程汉化感兴趣，我可以参与，我是过程系统工程的在读博士，主要做过程设计和优化，有一定的JuMP使用经验。