A suggestion for package maintainers

anon37204545
Sat, 01 Aug 2020 23:10:41 +0000
Community

If your Julia package has any form of online documentation (e.g. docs generated by Documenter.jl), please please put the link to it in the repository’s description. For example, just like in the Documenter.jl repository itself.

Here are some of the benefits:

1. A curious Julia user wouldn’t have to scroll (a lot!) to reach a useful link (it can be painful on a large display, let alone on the mobile device). Links to docs are often not on the top of the Readme, but hidden somewhere deep in the layers of headings. That makes things even more difficult.

2. People who are just exploring Julia’s ecosystem and aren’t aware of Documenter, stable/latest docs and how to find them, would just get lost without a very visible link. They are presented with undecipherable source code, and (apparently) no documentation for it. They will probably just close the tab and search for something else.

3. It’s good for marketing. A repository with a (docs) website is automatically percieved as more mature.

I opened an issue related to this in some repositories, and the maintainers unanimously accepted the suggestion. But I hope more will follow the trend without me opening more issues.

Bonus: is making a full-blown documentation too hard and time consuming? You can skip that and just make a nice web page with PkgPage.jl in under 10 minutes.

3 posts - 3 participants