It’s definitely true that the docs badges don’t seem to be noticed by everyone as easily as I’d originally hoped. Note that when the linked discussion about Documenter.jl’s use of badges happened there was also a link to the docs in the repo description as you’ve suggested here.
I think a good approach packages should be taking it to add links to docs in the following places (you can never have too many links): - the repo description; - as badges together with the other CI and coverage badges; - and in a separate section in the body of their readme page. That’s how Documenter has been doing it for a while now and I’ve had no further queries about it, so perhaps (hopefully) it’s working. miscellaneous things that I don’t need to care about unless I’m a developer I’d say that those status badges are actually more beneficial to potential users rather than developers in the sense that it helps people gauge the current “health” of the package. If you’re a developer you’ll probably more easily be able to work through problems you encounter with packages that may not be all that well tested yet. As a user it would probably be best to avoid packages that are probably not quite ready for prime time. That’s my interpretation of the usefulness of badges anyway. — Mike On Sunday, 14 August 2016 17:54:25 UTC+2, Scott T wrote: > > I keep overlooking these badges too because I'm used to thinking of them > as "miscellaneous things that I don't need to care about unless I'm a > developer". I like it when package authors put a link to the documentation > (or at least a landing page from where I can find documentation) in the URL > field at the top of the page so the first thing I see is repo name, > one-line description, link to docs. Boom, easy. > > On Sunday, 14 August 2016 16:11:26 UTC+1, Tommy Hofmann wrote: >> >> There was exactly the same discussion about links to the documentation in >> the announcement of Documenter.jl: >> https://groups.google.com/forum/?fromgroups#!topic/julia-users/8el-G75Tj1A >> >> Maybe it is not as obvious as people like to think. Someone not being >> familiar with Github or travis badges (e.g. think of a user who is not a >> developer himself) could have a hard time finding them. >> >> On Sunday, August 14, 2016 at 3:07:16 PM UTC+2, Andrew wrote: >>> >>> I also couldn't find the documentation for a minute. I think it's >>> because it's attached to the tests pass indicators, which I glossed over >>> due to lack of interest. >>> >>> On Sunday, August 14, 2016 at 4:22:26 AM UTC-4, Kristoffer Carlsson >>> wrote: >>>> >>>> What did you expect them to be? They are right under a big table header >>>> saying "Documentation". They have the same style as the other badges which >>>> are also clickable and have been for years. I think it is worth seeing if >>>> more people can't find the documentation before doing any changes. >>> >>>
