Could you please open an issue so this doesn’t get lost? As you say, folks often don’t know where the stumbling blocks are; and the only way we find them if is the stumblers shout out upon stubbing their toe!
8 Likes
I appreciate your view on this - and I do agree - it is kind of “american” to put a number on something semiarbitrary and arguably more american to take it way too seriously. But - it’s also completely optional, just like making packages 1.0.0 releases. We don’t have to do it, but having it available wouldn’t be so bad. We don’t have to have code coverage badges on our repo’s they are super arbitrary - but, some people appreciate them.
And yea the system could be gamed, but, I don’t see people in this communtiy as the type to game some numbers by writing bad docs, for something completely optional. Not saying a few wouldn’t - but, dunno. Hmmm…
1 Like
Asking documentation writers to link back very basic building blocks of Julia to the manual is unreasonable.
Perhaps it is unreasonable.
However, what does excellent documentation look like? Whatever that ideal is, the initial documentation isn’t likely to achieve it. However, over time, perhaps it can be refined to get closer and closer to the go
Some syntax elements are not not easy to search for. Say I see <: in code. What does that do? It’s not so easy to search for <: in the Julia documentation. God help you if you see a ? b : c and try to search for “?”!
IMO the right mindset is: don’t be a dummy. Invest in understanding things. It pays off.
Treat some parts of Julia like math. There is no shame in reading something five times to get an initial understanding, then coming back to it later to nail down everything.
Constraints on people’s time often prohibit them from making this investment. A person needs an answer, and he needs it fast, or he moves on.
I’m actually unusual because (… a lot of reasons, but …) I actually read documentation. I send big manuals to Fedex Office to print and put in binders. I buy books of documentation and read them. I would guess maybe 1 out 100 people do that.
3 Likes
Punctuation (operators etc) is definitely difficult to search for, maybe this could be improved. But trying to read Julia code without learning the basic syntax of the language is a very difficult way to learn the language anyway.
Taken at face value, this is an optimization problem that has no solution. You can’t learn something complex very quickly. It is perfectly fine to say that someone does not have enough time to learn the foundations of Julia, but then that person will just not be programming Julia without constant frustration and near-zero productivity.
Instead, what I think happens to people who “have no time” to make an initial investment into reading the manual is that they devote 5-10x the time to acquiring the same knowledge eventually, in a very frustrating manner. Some of course give up before that.
5 Likes
I opened an issue for a docstring
2 Likes
Punctuation (operators etc) is definitely difficult to search for, maybe this could be improved. But trying to read Julia code without learning the basic syntax of the language is a very difficult way to learn the language anyway.
I brought up the ternary operator specifically because I had seen it in code posted online, and I didn’t understand the syntax, but knew I wouldn’t get anywhere searching for “?”. Last week, while reading through the docs, I came across the ternary operator. “Wow, that’s useful.” Cryptic, but useful.
Taken at face value, this is an optimization problem that has no solution. You can’t learn something complex very quickly. It is perfectly fine to say that someone does not have enough time to learn the foundations of Julia, but then that person will just not be programming Julia without constant frustration and near-zero productivity.
It depends on the prior experience of the person coming to Julia.
Here are some of my priorities when learning a new programming language:
- How do I do loops?
- What’s the if-then syntax and other conditionals?
- How and strings handled and what are the string functions (I invariably end up parsing string data)
- How do I create a numeric array? What linear algebra functions are there? How do I fill a matrix with zeros, ones, random numbers?
- what stats functions are available? What are the functions for the Normal pdf and cdf? How is missing data handled?
- how do I create a function?
- How do I read data in? Write data out?
What am I doing? I’m mapping my prior knowledge to the new language, Julia. Not a bad way to get started (you can write FORTRAN in any language). The, over time, you learn more and more about what makes the language special – what features does it bring that makes programming easier than other languages?
Now, someone who has never programmed before, I would expect would begin at “Getting Started” and proceed linearly through the first several chapters of documentation.
The challenge of documentation is serving several audiences with one “documentation.” “How do I find a value in an array?” vs. “Here, gentle reader, is how we create an array.” Printed books can’t address that very well, but there is the possibility that an electronic hypertext system could, if you can get writers to create the content.
2 Likes
For some of this, Learn Julia in Y Minutes is great.
Strangely, it doesn’t mention cond ? one : two, nor &&, || which are also potentially surprising. (Nor does it mention broadcasting by dots.)
1 Like
I like your outline as a “get-started” document. I might suggest that something like that be done in levels.
- Level 1-basic syntax with basic examples,
- Level 2-more complex syntax and examples,
- Level 3-detailed syntax and “real world” examples
In learning Julia, some of the things that trip me up is my knowledge of other languages. Little things, like comments that I know from C/C++ and the “for a:step:b” took me quite a bit of document searching. Example: I spent about 3-4 hours trying to figure out the “for” statement because my mind was used to the C format.
The bad news: I spent a lot of time trying to learn something basic.
The good news: In the process of searching for an answer, I tripped over a lot of other information that I did use, or may use in the future
BTW: Dr. Bush’s work lead to Keyword-In-Context development, a technique for documentation that I find extremely useful. Here’s a link to a paper: https://apps.dtic.mil/dtic/tr/fulltext/u2/443912.pdf
Chapter I. Background, Section A, pretty much describes this problem.
This morning, the thought occurred to me that the most immediate improvement might be if list on the left of the Julia documentation for each section was expanded to have a link to each sub-topic and function.
E.g., The Strings section under Base could have a list of all the functions and a link to them. ordered by function name.
Note that there’s a dedicated page for punctuation here: https://docs.julialang.org/en/latest/base/punctuation/
But amusingly enough, I couldn’t seem to search for it in the sidebar, I had to hunt through the sections by eye.
5 Likes
I am very willing to help with documentation.
My absolute #1 pet peeve with any documentation is lack of simple examples. A lot of the documentation for packages is excellent but almost useless when starting out with a package.
I’ve actually managed to submit a PR and I absolutely could not do it again without randomly trying things until it worked, which is exactly how i did it the first time. I delete my trees and re-cloned or forked, or whatever it was, at least 3 times because i would get stuck at some point and had no idea how to proceed. github got into the action through ridiculous little drop down buttons that hid things that apparently i needed and didn’t know were there. it was extremely frustrating.
I’ve written simple examples for almost every single julia package i’ve used, and I just can’t bring myself to try and submit them to the docs because I know i’ll have to go try and figure out the PR thing again.
it’s a classic problem of everyone who knows how to do it already doesn’t think it’s that bad. but it is. it really is.
10 Likes
Kudos for being willing to contribute.
well, i find it a bit lame that i’m saying i’d like to contribute more and then complaining about PRs as a reason not to do it.
i will make another attempt at figuring out PRs again. I’m just pretty sure that the people who know and understand the package/PR environment don’t realize that it’s really not very easy, and figuring it out so that you can submit a 10 line example is a bit daunting.
Someday i hope to be in that group that thinks “it’s really easy, what’s all the complaining about ?” . LOL.
Julia is the language i was looking for 
and I do want to help !
3 Likes
I never did a PR to documentation. Do you simply fork the whole repo, modify whatever and then create a pull request? I imagine in most cases it doesn’t make sense to clone locally and use git; editing directly on github should work?
agree…I usually spend much time on learning to use an new package. It seems like learning a new language.
As has been mentioned before, for simple changes to the documentation, the entire process can be conducted through the github website, without ever creating a local clone of the repository. It’s actually quite easy to do this.
If you do want to make a local clone of the repository, this guide might be helpful:
3 Likes
For anyone who’s confused about how to submit a PR, here’s a video showing the steps required to make a PR to Julia’s README: How to edit the Julia docs on GitHub - YouTube
The video is under 30 seconds and should be easy to follow since it just matches steps from Editing files - GitHub Docs linked right above.
15 Likes