odow
commented
8 months ago Thanks for writing this up. Agree with trying to redirect where possible but agree it's a tricky heuristic to get right.
We are planning on adding a top bar to indicate to the docs.juliahub.com visitor that they are reading automatically generated (fallback) documentation
I think this has to be the top priority. Here are two examples from projects I'm involved in. There's nothing to indicate that these pages are a product of JuliaHub and not the first-party authors.
https://docs.juliahub.com/General/SDDP/stable/ https://docs.juliahub.com/General/Juniper/stable/
and that they should also check the package’s GitHub repository to see if there are other docs available.
Yes! A link to the original repo is very necessary.
Here's an example of a (now unmaintained) package of mine. There's nothing to link back (because why would you put a link to the GitHub in the GitHub repo :smile:)
DanielVandH
j-fu
Dattax
Summary:
JuliaHub.com builds and hosts package documentation, and we’ve been attempting to do that for every open source package in the General registry (unless opted out). The hope is to have useful documentation available on docs.juliahub.com for every package with a unified search and discovery experience that everyone can enjoy. But our execution hasn’t been perfect — we’ve heard feedback from package developers and others on multiple issues and are dedicating time and effort to improve things.
There are three concrete things we are aiming to improve upon:
1. Better detection of default hosting locations and alternate build systems
Currently, depending on the package, the documentation that is on juliahub.com is generated by:
But this isn’t great because the package authors (especially for more mature packages) have spent a lot of effort curating and building their self-hosted documentation. Paradoxically, the more thorough and therefore complex the documentation is, the more likely it is to fail to build automatically — and requiring a manual opt-out process is tedious and frustrating.
To improve the situation here, we are planning to make JuliaHub smarter about inferring whether the package has self-hosted docs or not. We are planning to trial the following heuristics:
We would also like to push the ecosystem to adopt standard Project.toml metadata, which would include a way to specify where external tools (including, but not limited to JuliaHub; editor tooling can also benefit from that kind of metadata) can find the documentation (https://github.com/JuliaLang/Pkg.jl/issues/1070).
We will not attempt to auto-generate or host documentation of packages for which the above heuristics succeed.
2. Mitigating “broken” docs
When documentation generation has failed due to one reason or another, JuliaHub serves a fallback with the README & docstrings. We hope that getting better at identifying external hosting will prevent many cases of broken docs in the first place, but in the event that we fail, we want to make what’s happening clearer to both package devs and users.
We are planning on adding a top bar to indicate to the docs.juliahub.com visitor that they are reading automatically generated (fallback) documentation, and that they should also check the package’s GitHub repository to see if there are other docs available.
3. Avoiding old and out-dated docs getting prioritized rankings in search engines
We hope this one is largely resolved! We have pushed out updates over the past few months that should force search engines to de-index old versions. Please report this to us if this is still an issue you encounter.