Looking for Ideas for the Package Overview Page on OCaml.org

As a package author I prefer to use the README.md as the content of the landing page. That way I have 1 main place to keep up to date and it is consistent between GitLab/GitHub and the docs site. We could use better tooling around executable Markdown files, mdx is great but has limitations when integrating with CI/odoc/source code. Additionally I could imagine using an index.mld to generate a suitable README.md and landing page for the docs.

I really like the crates.io package documentation eg https://crates.io/crates/tokio. It clearly shows what the project is, gives an overview, plus links for API documentation and tutorials. I would prefer it didn’t mention the last published metadata, I agree with @dbuenzli it is a poor proxy for the question “Is this project maintained?” “Is it established enough to rely on?”. For me the reverse dependencies count gives some of the popularity information but nothing about whether it is maintained. The current ocaml.org documentation site feels like it uses more blank space when showing the same information as crates.io, which I don’t personally like. The use of categories is interesting, we have tags in opam files that could be used for that but are not commonly used.

The area available for dependencies / reverse dependencies is a bit squashed, if I’m looking for that information I’d like to see everything and not have to scroll. Perhaps a tab or some other UI element is more suitable, and the main page could just show a count or some other summary.

4 Likes

I think this is a great idea. crates.io has a great link to “Try on Rust Playgrounds” that could be a really nice way to try out a package.

3 Likes

To echo the pro-.mld crowd, my index.mld files are where I lay out how to use my libraries and point to the API, examples, etc. The readme usually only gives a brief blurb about the library itself before sections linking to the generated docs and detailing other logistical concerns which I don’t think are as useful to have on a splash page for the package.

1 Like

I see people arguing for readme vs .mld files. Why not both? I would suggest looking at my earlier comment again: preview of the readme in a collapsed, expandable section at the top, followed by the top level docs of the package. If it has a top-level .mld file, that will be part of the odoc-generated output anyway.

3 Likes

Oh no, I actually meant to talk about “testable examples” :slight_smile:

As a documentation tool, see here: Testable Examples in Go - The Go Programming Language

You can see one in action on the redis package doc linked by @yawaramin.

Runnable examples are the icing on the cake though :wink:

See the documented function “Handle” from golang’s http library here: http package - net/http - Go Packages

But may require infrastructure which seems less reachable than obtaining testable examples AKA doctests first

1 Like

BTW is there a way to generate a badge (like almost every other package repository does) for an OPAM package that you can put in your README file? If not yet, I personally think it would be a great feature.

2 Likes

The problem is that, in the current state of affairs you will likely get redundant information and irrelevant contextual information. I’d rather have that as a separate link.

Having a lot of published packages (~40) I faced quite early the problem of redundant information to specify and can’t afford spending time on churn – which is only concomitant to the software practice if you decide to accept it. Just to give an idea these “oh it’s just five minutes of your time on your package” become 3h of soulless work for me.

So in the scheme I designed for topkg’s release process, later reused by dune-release. The idea was the following, if you don’t specify an opam synopsis and/or description yourself it is derived from your README as follows (atx headings or asciidoc are also supported):

$(NAME) $(SEP) $(SYNOPSIS)
--------------------------

$(DESCRIPTION)

# First header of any level

Now that works very well for opam.

However the thing is that in $(DESCRIPTION) may want to link in your package docset. This desire extends more generally if you try to use your README as your documentation (personally I don’t think that’s the place, simply have a link to your package docset in there).

The problem is that you can’t make this to work both on github and other documentation generation context – and I urge people to devise their docs so that are perusable in any documentation context, for reasons that go from offline perusal (e.g. air-gapped settings, retreats, etc.), to accessibility, to the possibility of having docset generated locally only for those package you use in your project, etc.

Since I couldn’t reuse $(DESCRIPTION) in my .mld, most of my index.mld start with slightly tweaked versions of $(DESCRIPTION) – I may try in the future to be more subtle about that but on the other hand since in index.mld the OCaml context is established there’s stuff like “this is an OCaml package” that would feel redundant.

I ended up having that little redudancy which you can witness for example in brr where the readme preamble is sligthly tweaked to this in brr’s index.mld with links in the docset. Having both README and index.mld here would just result in stuttering on the package page.

So I would rather suggest to have this (which is almost what odig has been doing for the past six years, I could tweak it to match it):

If there is an index.mld file, just use that. If not then use the opam description (which as a package publisher you can derive from your README, see above) followed with one section per library containing an automatically generated module index ({!modules:} directive) – ideally we would have a {!library-modules lib} directive but since that concept doesn’t exist in the toolchain we are left with hacks for now.

4 Likes

Having a structured way of signalling the expected maintenance structure of a package would be a good use of opam package metadata. I can imagine one field serving multiple purposes:

  • on publish, for the maintainer to signal the expected maturity of a particular release (from mature to alpha).
  • upon subsequent breakage, for the opam repository (or other) maintainers to modify the metadata for a released package to indicate that external changes (such as a compiler release) means that it needs maintainence, even if the original releaser has since dropped off the radar.
  • for sole-maintainer packages, signal the need for additional maintainers, and that they are (or are not) welcome to apply.
4 Likes

Is a little stuttering really that bad? If you take a look at my earlier link–most of the readme is actually hidden in a collapsed section. Scrolling past it will take like one swipe. Most people would likely read the top summary and then use the left navigation panel to jump to the section they’re interested in.

I am thinking the simpler we keep things, the easier it is to get something working out the door, then it can be iterated later.

1 Like

Yes.

Not sure what you found complicated in my proposal. This has been implemented in odig for ages.

1 Like

I’ve seen some GitHub README badges that indicate the percentage of the codebase that is documented. I’ve heard people complain that many OCaml libraries lack documentation besides type signatures. Could there be a way to display “percent documented” on the package page to incentivize people to document their APIs?

4 Likes

For package popularity, both gitlab and github already support tools to assess this in the form of stars. I would love to see a star count if available.

I would also like revdep count to also be displayed up front: even though it’s biased towards libraries, it is important information, as it means the package is being heavily used.

Finally, the last update date is very important information. A package last updated 10 years ago will likely not be integrated well into the ecosystem, may have security issues, and is also likely to lack the more recent enhancements in terms of performance and readability. Even a stable library requires minor updates to keep up with recent ecosystem changes. A long time gap usually indicates abandonment.

2 Likes

RE: README

I dislike the README idea mostly on the grounds that a lot of proposals are choosing README.md and Markdown has a) a lot of limitations for documentations, and b) so many forks (“flavors”) that it would be a nightmare to try to support everyone’s favorite option. “Renders fine on my GitLab page, why doesn’t feature X work on ocaml.org”. It also limits alternatives like AsciiDoc, reStructuredText, Djot, etc. Some code forges allow querying the rendered README via API (I know at least sr.ht does), but you can still end up with inconsistencies in CSS classes per forge down to the syntax highlighter (GitLab uses Rouge, SourceHut Pygments, etc.). I also agree with the original rebuttal that the content in READMEs varies wildly across projects that you don’t know you’ll get—including video files on some. There’s also been a feature creep issue where a lot of READMEs have morphed into RENDERMEs where they are unreadable as plaintext, filled with HTML and image-only badges that don’t help you read about a project when opening the file. There’s already a spot to link to one’s docs that could link to separate docs or one’s README.

RE: Stars

A few months back there was an issue with a projects that got to the Hacker News front page. When you linked your Microsoft GitHub account with the site, the project automatically starred itself. This ended up triggering the systems at Microsoft GitHub to ban the user that got locked out of their account. Star hacking and gamifying popularity contest are an issue. The amount of stars a project has should only be taken with a grain of salt as it doesn’t correlate with code quality. I would vote against including such information because I think it leads to too many users worrying about how popular their projects are and it also would disincentivize folks that want to use SourceHut, Codeberg, or self-hosting cgit, Forgejo—or not using Git at all in favor of Mercurial, darcs, Pijul, etc. Remember that Git is distributed version control, and centralizing on a handful of platforms goes against one of the core features. ForgeFed is looking to allay some of these issues hooking one’s forge up to the Fediverse to decentralize these features, but will likely not be on by default and not everyone wants their code to be a part of a social network like what ForgeFed is proposing and Microsoft GitHub and GitLab are currently offering.

7 Likes

It is very helpful to see you all spell out the consequences of possible choices and lay out the underlying reasons that led to the status quo. We are looking to uncover the most reasonable solution that will make sense for the years to come where we see the ecosystem flourish and where people can build more and more great things with OCaml. :slight_smile:

I would hate if we ended up having to move things around again in a few months or years, only because we put up an interim/shortcut solution now. There is a real cost to changes we make here: the content of the package’s “landing page” on ocaml.org may influence where you place which information in order to provide a great experience for onboarding users to your packages.

I will summarize all points and considerations brought up next week on Wednesday in this thread.

3 Likes

I think this is looking for a theoretical issue when the practical day-to-day usage of stars is fine. github and gitlab provide user verification for free. This allows them to come up with a popularity measure that has value. Is it a perfect measure? Of course not, nothing is. But all other things being equal, it lets us have some measure of the library or application’s true user count and satisfaction levels.

I don’t think we should aggregate multiple measures into some kind of score. Simply provide the facts as they are. This is the number of stars on this package (if available). This is the number of revdeps. This is the number of downloads, and this is when the package was last updated. Each one of the fields should ideally be sortable. That’s it.

2 Likes

Thanks for taking the task of summarizing. Would it be possible to also vote (a poll) on what goes on the overview? Not so much “which do you prefer” questions but “would seeing XXX on the overview significantly improve your OCaml development experience” or (if technically possible) “what are the top 3 things you want to see on the overview”.

I haven’t heard it mentioned yet, but I’d also love if the overview includes the findlib library names which today you have to click on the Documentation link to find. I find myself looking for that information the most frequently. But I may be unique.

6 Likes

Ok, so that was quite a bit to digest. Here’s a summary:

1- Debate about package quality metrics

Having “last published” and publication date in general displayed on the page might interfere with the visibility of stable packages that do not need improvement.

Ideas for other metrics:

  • (manual) self-assessment of package author. (Code quality, performance, maintainability, evolution, version >= 1.0.0 etc.)
  • (manual) Maintenance-related tagging: signal the need for additional maintainers, signal that a package needs maintenance
  • (automated) Signal broken packages.
  • (automated) Metrics from external sourecs: e.g. GitHub Number of issues / pull requests / star count
    • Contrapoint: supporting all options, including popular open source self-hosted optionsis a huge work item, and choosing just a few is inherently unfair
  • (automated) Weekly download statistics

2- Debate about displaying or not displaying README / opam description / index.mld on package overview:

  • Since README is publicly displayed on GitHub/GitLab etc, many people currently use it as a “public landing page” of the package.
    • Essentially, these other services encourage writing README in a certain way - in order to establish proper context within that other service
  • Challenge: Ideally, package authors should not have to repeat the same info in several places.
  • Aspects to consider wrt README:
    • different renderers on different sites (e.g. GitLab, GitHub, SourceHut, Pygments, etc.) support different markdown features
    • Nowadays more and more READMEs contain images or even videos, as well as tons of badges
  • Ideas:
    • Show a collapsible README on package overview
    • Instead of rendering README on package overview: add a link to the README (but where to, to the hosted repository or to ocaml.org’s rendition of README?)
  • Index.mld and other .mld files could be displayed instead of README. Additionally, links for API documentation and tutorials
    • Note: if you don’t specify an opam synopsis and/or description yourself, dune-release derives those from your README as described in Looking for Ideas for the Package Overview Page on OCaml.org - #40 by dbuenzli. However, when you want to link somewhere from within the $(DESCRIPTION) block, that will not work at the same time on GitHub as well as in other documentation contexts (e.g. locally-built offline documentation vs ocaml.org vs GitHub).

3- Playground functionality

  • “Tested examples”, i.e. ability to write code sections in the package docs that will be executed as tests during the documentation build - helps package users assess whether the documentation is up to date and makes it easier for package authors to update the docs when functionality changed
  • Ability to run code examples from packages in the playground
  • “Runnable examples” like Testable Examples in Go - The Go Programming Language - ability to write code sections in the docs that will (1) run as tests during the package documentation build step, and (2) render as an “inline-playground” within the surrounding documentation page

4- Other Feedback/Ideas

  • Allow URLs like https://ocaml.org/p/{PACKAGE}.{VERSION}
  • On package version dropdown - Add published date for each version
  • Security advisories / report package vulnerability
  • It would be nice to have badges for your package to display on the README so that the package repository looks attractive on the version control website where it is hosted
  • Package overview should show all the findlib library names
  • Dependencies, Reverse Dependencies and Conflicts need more space, as they can be quite narrow and tall

5- Package overview pages inspiration

11 Likes

I remember once seeing an OPAM build matrix page where the rows were packages and columns were OCaml versions. Could this existing data be presented on the package page? Whether a package builds could indicate its maturity and maintenance status without biasing packages with new releases over stable old packages.

EDIT: The page is check.ocamllabs.io:8080.

1 Like

I’m not sure if ‘package builds’ could act as a stable quality indicator. A package may build today but, many packages don’t have version bounds on their dependencies, and could easily break tomorrow. There are examples of version bounds being added to packages in the opam repository to fix breakages.

1 Like

I doubt there is other meaningful ‘quality’ markers than ‘know the people’ and ‘know the code’.

So what I like per package is

  • a stable, static landing page,
  • access to the source (tarballs of all versions)
  • some kind of an issue tracker and a forum like this to meet and discuss things. Friendly and frank,
  • dependencies visualised,
  • ideally hosted at accessible, reliable, non-GAFAM hosts. The plural is intentional. Having one is IMO pathogenic.

Most other is distracting cruft IMHO.

2 Likes