We are looking into improving the “Overview/Description” page of a package. Since this is basically the “landing page” of the package, it needs to both look great and include the most relevant info. We want you to be able to estimate at a glance whether the package is one that you might want to use, and to find the most important landmarks (e.g. CHANGES.md, LICENSE.md, Documentation, package homepage) of the package easily.
Share your thoughts about it!
What would be useful to see appearing on the page overview page?
We’re also very interested in your favorite package overview pages from other languages. Please do share screenshots of package overview pages that you really like to use in this thread. We are compiling a moodboard in order to systematically analyze how to best arrange the content that we have and to be inspired on what looks great while being usable at the same time.
Your opinions matter and your feedback is used to improve our work.
Here’s an example of the kind of page we’re talking about:
Please no “Last published” information. Consumerist culture has made it into software aswell but stable and mostly finished software exists and we should value it. “Last published” gives no valuable information to end users as to whether the software is maintained or not.
Also I don’t see the point needing one more click to access the API docs. This page should be the documentation. Just splice the index.mld if it exists and cookup something default if it doesn’t (see e.g. odig’s scheme). The current scheme just wastes my time.
I agree that we should make stable and finished packages more visible. Do we have any specific ideas how to do that? I am not opposed at all to replacing the publication date with a metric that is more useful wrt estimating “how viable is it to depend on this package?”.
I think… when choosing a package we may care about:
code quality - it’s always better to depend on a package with code that takes into account performance, ease of use, and maintainability
active community around the package - so that we know that we can interact with others using the same package and that there’s someone who would be open to reviewing and merging the pull requests for bug fixes we may contribute.
good documentation - to save time and struggles trying to figure out the relevant info by looking at the source code
It’s true that it doesn’t matter much when the package was written, or how new it is. Sometimes, a lot of new versions being published can mean that a package has a lot of bugs and everyone is scrambling to fix things (i.e. this would be a negative signal regarding (1) but a positive signal regarding (2)).
Are you sure you want to include Microsoft GitHub avatars? I find them a bit distracting in a non-communication platforms, consumes bandwidth, is limited to a proprietary platform, and causes misalignment when author/maintainers lack avatars. An example is mirage
Thanks for the feedback, this is useful. I agree it looks really off when one author/maintainer of a list has an avatar, and the rest doesn’t.
I think you’re right: it makes sense to have avatars when we can be sure that everyone has one (e.g. NPM does it by requiring everyone to make an account in order to publish to the NPM repository).
We have noticed that as well: Many projects have a wonderful README page that is written with the intent to onboard a new package user, and it would be so useful to show that.
Maybe we only want to fall back to the opam description when no README exists? Or always render both of them?
I suppose we cannot retire the opam description altogether because other tools may depend on it?
I know programmers like to derive nonsense qualitative metrics out of flawed quantitative data but what about simply not doing that ?
Just provide the relevant links (package home, package issue tracker etc.) that allow programmers to asses your points by themselves.
Note that even stuff like number of recursive revdeps in the opam repo is irrelevant since it biase towards library usage rather than application usage. A package may have none of the former but a lot of the latter.
True, the reverse dependencies are also a very limited view at how established a package is within the community.
So far, the most reliable estimate of usage I have seen in other languages is “downloads per week” - that can still be misleading, but at least it paints a clearer picture by not discriminating inherently against application usage.
I don’t think readme are a good place to have these bits. README are for a short description of the project and bureaucratic information. They should be made to stand on their own, regardless of ocaml.org’s existence. If you embed them in ocaml.org they will feel redundant, just provide a link to it.
For onboarding package users we should rather entice users to write good index.mld pages and additional .mld pages. These .mld files understands (as in link) your API docs, they are better suited.
An opam description is a very different thing from a README. Your release process might derive the former from the latter (I suppose dune-release does, at least topkg did so it might still be there), but they are clearly not the same thing.
I think they provide a terrible user experience. The hyperlinks of your READMEs variously point me to ocaml.org, to your rendering of your API docs or in the README itself. All that is going to be worse if it ends up rendered on ocaml.org since your link into the API docs are going to be on your render of the API docs rather than those of ocaml.org. Finally none of this perusable locally or offline via odig.
.mld files do not extract documentation from code, they are standalone, documentation files that your API documentation tool understands.
Writing a .mld file and installing it is as low effort and has the advantage of making correct links in the documentation infrastructure wherever it gets rendered, on ocaml.org, on your local docsets via odig, on the doc sets generated by your build system, etc. And since you mention maintenance, it checks the validity of your references too…
Some other people like system packagers are. You also get all sorts of grab bag information like community guidelines, licensing, authors, how to report bugs, where to ask for help which don’t make it up for a good package landing page on ocaml.org: there is a lack of uniformity and some of these bits are already available via the package metadata.
The context of an ocaml.org package landing page is different from the context of a github README. I don’t think blindly reusing that content is a good idea.
That point is orthogonal to whether the README should be used as the entry point for docs.
@dbuenzli Daniel, I appreciate that you point out in detail the technical consequences of a particular way of writing READMEs, as that’s helpful for us all to see where we stand and what options we have moving forward. However, can you try to make it sound a little less confrontational (e.g. terrible → bad / not great)? The use of strong words can cause people to interpret all that you write as unnecessarily abrasive or extending beyond what you actually mean.
@polytopic: I looked at GitHub - ocaml-multicore/kcas: Multi-word compare-and-swap library and with my application developer hat on: I really like this overall style of documentation where you first summarize the package and then onboard me into using your package. I can see that you put in a lot of work to make me as a user feel welcome and equip me well so I can use the package successfully.
Considering that
packages are often hosted on the web via services that display git repositories as websites, and
these web services tend to display the git repository’s README as a landing page
search via internet search engine for packages would lead to the package’s repository page on these web services,
there was/is clearly a need to write a decent README if one wanted to see their package adopted.
As a package author, ideally, I wouldn’t have to write the same “elevator pitch and onboarding” page in two different places.
A good thing about index.mld is that it is also embedded in the package itself.
Since we have never had a central place for hosting OCaml package documentation before, there’s not yet been a strong drive for favoring writing index.mld files over READMEs. I suspect that ocaml.org providing just that may make it more amenable to write an index.mld and then refer in the README to it?
(Just summarizing and collecting points, underlying causes, and needs as you bring them up.)
Very long READMEs will dominate the page and may include info irrelevant to getting an overview of the package. But linking to the README, if it exists, would be very welcome.
You can also check RubyGems for some ideas in this direction - here’s one such page. I’ve noticed that most established communities have more or less the same package overview pages.
If there are no dependencies or reverse dependencies, please say “None” rather than leaving it blank, which is confusing. (The alternative would be to hide the entry entirely but I think that might confuse people who are specifically looking for that info.)
I’ve noticed a small bug on the current page - “Last published” is actually “Published”. It’s the date on which a particular version of a package was shipped. RubyGems has a nice overview listing all releases with their release dates that I’d love to see here as well.
While someone commented it’s bad to highlight those dates, as people generally prefer “actively developed” packages these days, I do think that for every “done” project there are probably 100 abandoned ones.
I respectfully disagree . In practice, we live in a github/gitlab world for most packages, and both render the README by default afaik. That means the README is the de facto landing page for most projects. I try to write mine as such, with an explanation of what the project is, how to get started with it, etc. whereas odoc documentation becomes useful only after this context is established. With the existence of mdx, a README.md can also serve as checked documentation (which I use in some places for a little tutorial).
For an example of that, see containers’s README. I’m not claiming it’s great documentation but I’d be super annoyed if I had to write that in odoc.
Package metadata, readme, and toplevel documentation on a single page, much more efficient for everyone
By default show a limited part of the readme and collapse the rest so it can be easily expanded and collapsed again and by default doesn’t take up much space on the page
Left panel only for package documentation navigation, both contents and index. Having both left and right panels takes up too much space from the actual content
It is probably not a useful suggestion for a metric, but personally when selecting dependencies one of the first things I do is to grep the sources for Obj, look at the occurrences, and usually deprioritize that package relative to alternatives.
On ocaml.org the context is already established. Github is not ocaml specific, there’s another context to establish.
Not sure exactly what the problem is with that. You want your docs be part of the fully cross referenced OCaml documentation web space (as defined by odoc). You can simply have a link into that space from your README.
. In practice, we live in a github/gitlab world for most packages, and both render the README by default afaik. That means the README is the de facto landing page for most projects. I try to write mine as such, with an explanation of what the project is, how to get started with it, etc. whereas odoc documentation becomes useful only after this context is established. With the existence of mdx, a README.md can also serve as checked documentation (which I use in some places for a little tutorial).