In the above mentioned article, I discussed how in my perspective, the problem with Julia’s documentation is rooted in Documenter.jl. Software engineers are lazy, and this is even more true when it comes to software-engineering documentation. It can be incredibly stressful to go through the entire mission of developing a package. After the package is developed, then testing it vigorously, making some files, selecting a license — and finally — a release… But then realizing you still must worry about documentation.
Fortunately, Documenter.jl can be used to automate this process. Furthermore, documentation for packages is automatically consistently generated on the Julia Hub website. Needless to say, this is a very awesome approach, however, is this simply too easy? Let us also remember that all you must do to document software with Julia is just call an autodoc macro. That being said, while many mainstream packages instead opt to write a full description inside of the Documenter files, which is a good thing.
That being said, I think this also makes documentation so easy that it is easy to just graze over. Needless to say, that can be problematic when the only things one may work with is doc-strings, which may rarely feature examples, or complex descriptions of types. Needless to say, it is certainly optimal to have well-written documentation over simple auto-generated doc-strings in an HTML document. That beings said, it is just too easy to do the latter, which I think has damaged documentation.
Another thing that has damaged Julia documentation is that many users do not even know how to document their software. Why is this? Because believe it or not,
Documenter.jl, and documenting Julia in general is POORLY DOCUMENTED.
That is some hilarious irony to me. Just imagine;
“I cannot document my package, because the package I need to use to document my package has poor documentation.” That is not even it, however, there just simply are not a lot of comprehensive write-ups on Julia that explain how to do all of this — which can certainly be frustrating! Some Julia programmers do not even know that Documenter.jl exists!
The biggest reason why Julia software is very often undocumented, or very poorly documented did not even cross my mind when I wrote my previous article. It was not until after when I got a response from another fellow Julia programmer and fan talking about how they also experienced many issues with documentation as well. Actually, they…
Continue reading: https://towardsdatascience.com/why-julia-code-is-so-hard-to-document-properly-abccec3a42a?source=rss—-7f60cf5620c9—4