As someone new to Julia trying to learn it by reading the online manual https://docs.julialang.org/en/v1/index.html I wanted to provide some feedback.
- 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.
- 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.
- 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.
- 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.