Some comments on the Manual

New to Julia
1

As someone new to Julia trying to learn it by reading the online manual Julia Documentation · The Julia Language I wanted to provide some feedback.

  1. The manual isn’t very suitable for linear reading.

Having a good linear order will benefit those who want to learn the language by reading the manual from the start. And it will benefit those who like to jump about to read the bits of interest since its structure will be much clearer to them.

Example: Documentation and Metaprogramming could both be pushed back to later in the manual because they are more relevant to library writers than application writers (especially when people are starting out).

Example: Calling C and Fortran Code is more advanced than Environment Variables, so the former should go after the latter. Embedding Julia is the most advanced topic (since it depends on knowledge of C) and so should be the last topic.

Example (more personal): I find the Modules chapter very confusing and I don’t really believe that all the examples in the Summary of module usage table are correct. Nor does there appear to be a cross-reference to the Code Loading chapter which is surely relevant even if marked “for more advanced information see …”.

There are many other examples both of chapters and sections within chapters which if moved would make the manual easier to read.

  1. Any future additions/movements of chapters or sections ought to be done in agreement with the person responsible for the restructuring.

This will ensure that the manual remains coherrent.

  1. A consistent policy for presenting more advanced material ought to be applied within chapters and within sections.

One strategy is to separate advanced material into its own chapter(s)/section(s) and add cross-references at the end of the relevant basic/intermediate material.

Another strategy is to ensure that advanced material is always put at the end of the relevant chapter/section with a note indicating that it is advanced and can safely be skipped when first learning the language.

Applying either of these (preferably only one or the other) will make it easier for people to learn without being intimidated, and yet still being aware that advanced features are available when they’re ready.

The third suggestion is one that could be beneficially applied to restructuring the manual itself.

  1. First examples should be simple.

I find that examples are often more complicated than they need to be to teach the syntax or function at hand. Keeping the first example(s) simple makes it much easier for learners to focus on the syntax or function usage being taught. More realistic examples can always be put at the end.

2 Likes
2

An additional comment from my side:

There is a difference between an introduction and a documentation. So far we haven’t clearly made a distinction between the two, there was just one (rather linear) documentation. With all the progess and the “move things into stdlibs and external packages” going on, I think this old narrative got disrupted a lot. And I’m not sure it can be maintained at all. Some of the stdlibs are essential (adding packages for example) but are far down in the documentation (navigation bar). But certainly some of them are not. Should we group them as stdlibs (more documentation style) or according to importance (more introduction/tutorial style).

3

One approach that can work well is to have a Tutorial which teaches enough to get going and introduce Julia fundamentals (and esp. differences from other languages), but which is not exhaustive. And then to have a Language Reference and a Std. Library Reference.

Python’s docs use this kind of approach (although I personally don’t really like their tutorial). What I’ve found is that after years of Python programming I almost never use the Language Reference and spend most of my time using the Library Reference.

4

You make many relevant points, but just pointing these out in a topic may have less impact then proposing a correction in a pull request.

1 Like
5

I have started to edit the Julia manual to help improve it, but my input is mostly smoothing and clarifying the English.

I can’t propose changes to examples/usage/etc. (except trivial changes for clarity) because I don’t know Julia well enough to be sure of doing things idiomatically. And for the Modules chapter, I just don’t understand it, so can hardly fix it!

The biggest change needed is to restructure the manual. However, this needs someone who both understands Julia well (not me, I’m learning it), and understands how to structure a manual or documentation set for learning and reference.

So, I’m doing what I can at the small scale but can’t help with the big picture – except to point out there are problems there.

1 Like
6

My view: the Julia Manual is the Julia Reference Manual. (Or the other way round.) Its occasional informalities shouldn’t lead you to doubt its authority. I don’t think it’s intended as a tutorial.

There are loads of tutorials listed on the Learning page of the Julia web site Get started with Julia. Probably one for many tastes, ranging from Think Julia to various quick-starts and cheat sheets, and long lists of tedious examples in the form of a wiki. And there are things like Learn Julia the Hard Way which is currently abandoned but doesn’t need to remain so. Perhaps there being no officially sanctioned tutorial is a problem? And if you’re under 18 you’ll probably want head over to YouTube rather than use text-based training material anyway. :grinning:

1 Like
7

Fair enough, but I don’t really think that’s the intention of the documentation. As others have pointed out, it’s not a tutorial. Tutorials are certainly useful, but structuring the main documentation that way might render it less useful in the normal course of using the language by burdening it with trivialities and step-by-step procedures which may be uninteresting in most circumstances.

I’m not disagreeing with your assertions in regard to the documentation’s lack of suitability to beginners (though, I do think it’s probably not too bad a format for experienced programmers of other languages), and I definitely agree that such documentation is good to have, but in my opinion everyone would be best served by links to tutorials (or other formats more suitable for linear reading) somewhere early in the existing documentation where it is easy for everyone to find.

As I recall several good tutorials exist, but I don’t recall where they can be found. Likely the authors will chime in at some point and point them out to us.

There are two areas in which I consider the manual to be lacking:

  1. API docs. They aren’t bad, but in many cases they could probably be expanded. One pretty good example of what I have in mind are the numpy docs. Fortunately, I think we’re a large part of the way there, but some of us should probably go in and lengthen some of the doc strings of Base and stdlib functions in the code.
  2. stdlib docs. In some cases it’s really hard to figure out how to go use something. For example, there was another thread where a bunch of us were trying to figure out how to use the logging functionality. I agree that there needs to be a little bit more in the way of examples and use cases. I’m not arguing for tutorials here (though I think links are always welcome), just something more akin to the main docs, which I think to a pretty good job of conveying how to use most features.
3 Likes
8

I think that having an official Tutorial would be much better than a list of (possibly not kept up to date) ones. And it would also give people an official starting point so they’d feel confident that what was taught was up to date and good practice.

2 Likes
9

Yes, there’s:

A curated list of useful learning resources to help new users get started can be found on the learning page of the main Julia web site.

in the Getting Started section. I suppose it could be made bolder. :slight_smile:

10

Jane’s videos are the closest to “officially sanctioned” I’m aware of.

11

i appreciate the time you have taken to give feedback.

as i am sure you understand writing documentation is hard.
really hard.

1 Like
12

FWIW, I read the manual from cover to cover (at least the “Manual” proper) when I heard about this new language called “Julia” and some outlandish claims its proponents were making (they turned out to be true). It worked very well, answered a lot of questions, and raised many more which were answered in the forum.

I don’t even expect novels to be fully linear these days, so I think the manual is fine for learning the language, and can be worked through in a day by an experience programmer, or at most a week with a few hours every day. I also think that when one is learning a new language, it is reasonable to expect an initial investment.

4 Likes
13

I want to echo what @Tamas_Papp is saying. I was on a bit of a language-trialing binge when I first came to Julia, and the Julia manual got me up and running much faster than any other language’s documentation that I tried and definitely didn’t have any glaring omissions; it was seriously one of the reasons that I stuck with Julia (not the biggest but definitely a factor). Part of that is that Julia operates under a more familiar paradigm than some languages I was playing with (scheme, pony, OCaml, etc.), but part of it is that the manual is just better written (I had a much more pleasant time with the Julia manual than I ever have with the python manual, and it clearly exceeds the Nim manual from my language-binge). I wouldn’t want the manual to go to a more linear format; that would have significantly hindered my ability to learn Julia quickly I think.

That said, experiences may differ for people without experience in other languages. Maybe we could adopt one of the existing tutorials as the “official” Julia written tutorial?

3 Likes
14

Rust is famous for the quality of it’s manual