JuliaRoadmap 调查*1

JuliaRoadmap是一个计划,旨在帮助用户更好地了解、掌握和精通Julia,提供学习路径、资料整合和现有经验,提供对应练习,解决现有中文文档的不符合认知规律等问题。

当前仓库处在

希望做贡献的请先阅读根目录上的CONTRIBUTING文件,若有疑问请向我联系
希望长期做贡献的可以私信或联系rratic@163.com并提供github用户名,我会酌情发invitation


根据原投票结果,本因由JuliaCN组织维护,但johnnychen94反馈管理员没有精力,故创建JuliaRoadmap组织


欢迎有意向者踊跃贡献,你也可以向我们提出宝贵的意见,谢谢。


考虑到当前贡献者较少没有贡献者,现进行调查:没有贡献的原因是

  • 没有时间
  • 没有精力
  • 没有能力
  • pr操作麻烦
  • 不喜欢这个项目
  • 不清楚贡献方式

0 投票人

关于

贡献规范v1.0.1

贡献流程

  • 小幅度修改可以直接pull

  • 大幅度修改(包括新建)操作请先在Discussion处规划

文件结构

说明

块名 描述 层级 outline names tags tagnames 备注
meta 类似如何学习、相关工具介绍的文档 多层 Y Y
basic Julia 基础语法 单层 Y
advanced 语法进阶(除basic外的重要知识点) 单层 Y
packages 包的介绍与各包使用方式 单层 Y Y Y
algorithms 算法介绍与相关实现 多层 Y
ecosystem Julia 生态环境 多层 Y
knowledge 相关常识/知识 单层
tips 解决how-to问题 多层 Y Y Y 严格界定方式见后帖
pieces 相关代码片段 单层
lists 相关列表 单层

setting

outlinenamestagstagnames信息存在各setting.toml中,没有的应省略

提到文件时应省略后缀

outline

一个Vector{String},表示提纲,以HTML导出时会作为侧边栏且安装原顺序和层级排列

names

一个Dict{String,String}表示各目录的中文

tags

一个Dict{String,Vector{String}}表示各文件的标签,仅应包含同级目录中的内容

tagnames

一个Dict{String,Vector{String}},表示每个原tag可能的其它表达形式

命名规范

  • 除去后缀后名称不应相同

  • 仅由小写字母、数字、下划线组成

  • 目录命名名词使用复数

  • 文件命名名词使用单数

格式规范

参照已有样例,允许按照实情进行一定程度的改动

  • 使用utf-8,允许CRLF/LF

  • (尽量)使用Tab缩进

  • 使用Markdown,特别地,是julia-markdown,使用反斜杠\换行

  • 文档开头使用h1的标题,之后就不应有h1

  • 如果文档信息有来源,请以脚注形式加在页面底端,如果是该信息是结论,则应在该结论后标记对应的脚注链接

  • 较专业性的内容第一次出现使用翻译名(原名/缩写)

  • 如果文档有相关练习资源,在末尾(脚注前)添加## 练习,然后使用列表

    • 对于hydrooj习题,格式为[Hydro 域名 题目id](完整链接)

    • 对于leetcode习题,格式为Leetcode 题目id

    • 对于lightlearn,格式为LightLearn 关卡id

    • 欢迎增加资源

  • 对于代码块名称

    • 不能留空(使用plain

    • Julia 代码和REPL均使用jl

不知道你打算怎么组织 Roadmap 的内容

你先看看目录结构,到时候我可能会专门写文档说

EDIT: 已在CONTRIBUTING里添加了相关栏

已将https://discourse.juliacn.com/t/topic/6193 内容合并至

话说主页有一个语言生态块,谁有空可以推一下

我在slacks上问到了两个项目,这两个项目可以拿来练手,提高Julia编程能力

1 个赞

我现在发现中文文档中有些(不知来源的)错误信息
包括但不限于 数学运算和初等函数 · Julia中文文档 中提到的nand等实际不存在

julia> nand
ERROR: UndefVarError: nand not defined

版本问题

抱歉
但是版本问题(而且是LTS不支持的)好像应该要有一个框,即
!!! compat 1.7.0
不太清楚是否应该加入roadmap中。

这个更合适的地方是直接在上游文档进行修复 https://github.com/JuliaLang/julia/blob/afdd6bd2795ade4713259c1e4a651d8420ecfe83/base/bool.jl#L75-L141

对应的 PR 是 https://github.com/JuliaLang/julia/pull/40339 估计忘记加 compat 了

快去搞个 PR 蹭个 julia contributor 吧

所以说没有人弄同或

1 个赞

我这边依据最近的帖子写了一套问题/经验分类机制,大家可以借此充分提供自己的经验


(在tips/目录下)

tips整理规范

核心

解决可以用how描述的问题

遵循命名仅由小写字母、数字、下划线组成的规则

避免X-Y问题

词组处理

  • 若需要泛型方法,在最前加上any_

  • 大类(若是缩写或有较大歧义)+核心词+定性(名词,若有),用_串联

目录分类

call

描述:解决如何调用xxx的问题

准备:你需要调用什么?它的准确描述是什么?

示例:R 语言调用方式 => rlang.md

diff

描述:区分
准备:区分哪些东西,找到最短英文描述,按照首字母排序
举例:missing-nothing-undef的区分 => missing_nothing_undef.md

error

描述:解决报错问题

准备:找到错误类型名

示例:OutOfMemoryError的处理方式 => outofmemory.md

fix

描述:修复一个问题

准备:主语是什么?问题的核心名词是什么?

示例:类型推断失败 => julia/typeassert_failure.md

get

描述:获取什么东西

准备:主语

示例:获取.xls文件数据 => file_xls.md

judge

描述:判断/估计什么东西

准备:需要(need)、现有(exist)、结果(result);主语

示例:判断开多少线程 => need/task_number.md

know

描述:知道/(快速)了解什么东西

准备:主语

示例:任意包 => any_package.md

transform

描述:转化

准备:源、目标

示例:markdown转pdf => markdown2pdf.md

tag

标签应包括目录分类、大类(可能有多个)和定性


P.S. 我准备添加一个CS常识/相关知识模块。之前看到一个cs-wiki有人star,今天看了一下,啥都没做

pieces样例
lists样例

这个怎么感觉越来越像是教程而不是 roadmap 了…

啊这,
一个主要原因是,按照原定的计划,我当前做的一定程度来说确实是偏教程的东西,使得结构方面有这么点shadowing的问题
填充方面之前有人指出的几个方向是guide、tutorial、reference、document,中文文档基本上能解决refernce的问题,所以我尽量是保持在一个写newbie-tutorial同时靠note和link解决完整性的情况
如果可以的话最好给出指向性的、有建设性的方案,谢谢

先从简单的做起吧,步子别迈太大

我现在做的基本上是效率最高的部分:以前有文可以抄,用关键字搜索加点footnote
不太清楚你们需要的主体是什么,内容上这个目录划分应该给予了一个包容性的话题
我明天先提供各个扩展性适中部分的plan

如果真的想做这个,工程量会是很大的。一个大问题是:这个roadmap是写给谁看的?预设了读者的什么背景?英文社区的教程或者书籍,要么是大学里某门课程的教案,要么是某个workshop做技术培训面对已熟练掌握一些其他技能的专业人员。Julia本身仍然在发展中,就连自身的文档说明部分都远不及MATLAB等同类工具完整。举个例子,如果我是名本科生,正在学习微积分,我一开始可能什么工具都不会用,直到某一天有人告诉我用Mathematica可以直接求解各种积分,我会好奇并尝试使用它提供的微积分工具,然后进而可能了解这门语言的其他功能。我们做这个roadmap,目的不是越俎代庖,而是快速将用户导向他关注的功能。

由于Julia的开源社区属性,我们无法奢求一个像MATLAB一样集成在一起的大型文档,从教程到函数说明一一列举。我们可能能够实现的,是一个真正的地图,找到起点终点,然后自己走过去就好了。我建议在roadmap中省略所有类似教程的部分;同时,明确这份东西是给什么背景的人看的:小学生?大学生?资深码农?科学工作者?

2 个赞

我一直以为MATLAB没文档

  1. 先说受众问题
    我一开始的设想,是希望它适合任何人(按照julia现在的发展状况,也许抓些下沉市场是有必要的;对于当前情况来看,这个目标也许太大了)类似教程的部分……主要解决官方文档不符合认知规律的问题,也许没有刻意去教程化的必要吧(我之前也提到过,如果让用户到处链来链去就不太友善,因此放了些较为概括性的文字) 这个应该是最符合(我的)想法的例子,可以看看
  2. “而是快速将用户导向他关注的功能”
    这一点也许注重的是packages部分,那么我会提出一个疑问:如果是获取需要的东西的话,那么只是提供搜索工具不应该是足够的吗,看包的文档不就能解决吗,那么如果这里有问题,首先应该是各个包开发者的文档没有写清楚,在工作量上显然无法解决;又或者所说的是类似于隔壁 [视频课程] 搬运和翻译 julia-gpu-course (help wanted) 的方向,这一点上我给不了太大的帮助,用包我一直是用自己需要的东西,并没有去了解其它的话题。那么这边的框架我会尽快搭;又或者是之后会在tips那边给出的搜索页面?之后我给点打tag例子;
    如果a是名本科生,正在学习微积分,那么a拿到roadmap后我希望他做的是看完basic部分,(后期)酌情看advanced部分,看packages部分,至少提供了包搜索工具链接,然后凭借理应具备的英语能力阅读相关专业文档,这条路的优化空间不大
  3. “是一个真正的地图,找到起点终点,然后自己走过去就好了”
    那么这里的问题在于,不同人起点不同、终点不同,适合的路也不同,所以我的想法是节点化。也许之后需要添加一些页面进行串联,进行路径化

这是我放在meta目录下的如何学习章节,大家或许可以看看这篇如何修改?

备案号:京ICP备17009874号-2