As someone who has often cursed at the documentation of Julia packages and often looked into the source code to figure out how to use them, I’ll chime in here and give examples, even though I hate pointing at people.
So first of all as a clarification, a thousand thanks to the developers of the packages I’m about to mention as a negative example, I’m really grateful for their work, and without them the development of my own package would not have been possible at all. I am fully aware of how difficult it is to write a good documentation, and I also confess to have failed at it sometimes.
HDF5.jl probably gave me the most headaches. It starts with outdated information about supported data types, (by now much more is possible, like tuples and under certain conditions also structs, but what exactly you have to test yourself). The information about Parallel HDF5 and especially collective I/O is very sparse. And I also failed several times to find information about other things. Unfortunately that was a long time ago now, so I don’t have the details in my head anymore.
So let’s take two examples that I stumbled across this week, and from actually quite well-known and widespread packages. With Makie I always struggle to find the information which keywords I can use when. Try for example in the REPL “help?> Figure”. There is then a “No documentation found”. In addition a search function on the web page, which always gives only “No Files found” after you hit Enter. Why Franklin and not Documenter was used for the page is generally not clear to me. Try to find information about scatter! on the Makie webpage and compare this with geom_point on the RDocumentation/ggplot webpage.
Then I took a look at Genie.jl this week. I have developed a somewhat larger project with shiny in the past under a lot of time pressure, where I still do not completely rule out a reimplementation. The documentation of Genie.jl seems quite good for now, but I need to build a dashboard. And the one from Stipple, which is supposed to be used for this, the documentation actually only consists of the API itself, without any tutorial or the like, which somehow gives you access.
These are all experiences that I didn’t have before in other “bigger” programming languages (maybe with the exception of Scala). So it’s really hard for me to recommend other people to work with Julia, as long as they don’t really need the features. I really know that it’s hard to write good documentation, and failed often enough myself. I am fully aware that writing good documentation is hard, and I have failed often enough myself.
And that while I think Julia is a great language. I don’t know of any other programming language in which I could have developed Vahana.jl. And I think agent-based modeling in general is an area where Julia shines, not just because of on Agents.jl (which has really great documentation, by the way), but because here the computationally intensive parts have to be executed in the programming language in which the model is written.