Documentation of stdlibs?

Looking through the sources julia/stdlib at v1.7.0-rc1 · JuliaLang/julia · GitHub and comparing to the corresponding documentation, it’s unclear which modules seem to be stdlibs or not. As an example, Tar is an stdlib (seemingly added in 1.6?), has a NEWS.md entry for 1.7 but not for 1.6 (and NEWS.md for 1.6 makes no mention of it), yet the documentation can only be found in the upstream repo itself. Similar problems exist with ArgTools, and NetworkOptions. Does that mean these are less of an stdlib than other packages, e.g. Distributed? I think all of these were added in 1.6 (at least NetworkOptions and Downloads were, according to this blog post, but only Downloads seems to have managed to get documentation that shows up in docs.julialang.org. To someone who doesn’t know about the blog posts above, these stdlibs may as well not exist, since they’re not discoverable at all without someone telling them that they exist.

What constitutes an stdlib? What quality requirements do we have for an stdlib? What quality requirements do we have for the documentation of an stdlib? What’s the process for deciding what gets documented (do we have one…?)? How can we do better here? Can we maybe look to other projects for inspiration (the very extensive documentation of rust comes to mind)?

2 Likes

It means that I ran out of steam doing all that busy work and was hoping someone else (or myself in the future) would do some of that busy work.

2 Likes

Thank you for that insight and thank you for writing these libs in the first place! I remember 1.6 seemed very exhausting from an outside view. From my point of view, in most cases it’s unlikely that someone else will later take this work on - on the one hand because they’re not familiar with the code base and its intended uses, on the other because they may not be aware the code exists in the first place… Maybe the release process could be amended to specifically include a documentation pass, without which a release cannot move forward? This could look like the following, possibly inserted as part of/after feature freeze:

  • Review merged PRs
    • Do they need (more) documentation?
    • What documentation should be included/amended/changed?
      • Cross references
      • Intended API
      • Rewording
      • Deprecation/removal notices
    • Do they need a NEWS.md entry?
  • Ping PR authors in their PR, requesting additional items.

This is of course just a draft/quick idea, but I’m not familiar with the release process in greater detail than what I can observe by following the github repo and what’s been written up in that blog post, so I’m unsure how this would work in practice. In particular I’m skeptical in regards to pinging PR authors of merged PRs or delaying a release - it really feels like something similar/more stringent could be done before a PR is merged…

One part I somewhat disagree with though is, if I understood correctly, that this would be busy work - in part because I sometimes struggle with pointing people to the correct documentation when I find out that it either doesn’t exist, is out of date or isn’t clear about how it’s intended to be used (the Pkg docs come to mind - they feel more like a guide for an ideal world than full documentation and it seems like there are a number of new switches that aren’t mentioned in the full documentation at all). I’ve recently had the unfortunate pleasure of being in a conversation where the other party told me that they dropped julia in part because they couldn’t fit their head around the documentation and found it confusing :confused:

To be clear, I don’t want to lay blame on anyone in particular here - I want to start a discussion about how we can do better in that regard.

Creating an index file like this is what’s required:

It’s busy work in the sense that it’s tedious, doesn’t particularly require much skill (could be automated even), and it’s hard to remember what to do since it’s not done very often. If we want to enforce this (which we should), we could add a test on the Julia side that all stdlibs have such an index file.

4 Likes

Maybe we should open an issue to track this?

We can check for the existence of the docs/src/index.md file when we generate the documentation for stdlibs.

Thank you, that’s a good suggestion! How/where should this be added best? Just exiting here with a non-zero error code, to indicate to CI that this is missing? How do we enforce this if another PR that adds a new stdlib doesn’t update this section of the docs (see the list containing Pkg above your quote), which seems to be the case with all external stdlibs… I think an even more systemic solution is needed here.

I also checked the curious comment above that section, stating a need for this code until Fix CurrentModule example in manual by nalimilan · Pull Request #522 · JuliaDocs/Documenter.jl · GitHub has been finished - which it seems to have been for more than 4 years already :grimacing: Though it’s not immediately obvious to me why that PR in particular is relevant to generating doc links… maybe it’s a leftover from ye olden days of the old docs?

Ref missing documentation index file for new stdlibs · Issue #38462 · JuliaLang/julia · GitHub

1 Like

@kristoffer.carlsson add this comment, so can we remove those lines now?