I do find myself sometimes wishing that there was a more general way for authors to link-out to additional documentation from withing a doc-string.
This is exactly my hope as well, for either Grimoire or another tool.
My workflow is based on minimal interruption and staying in the editor for as long as possible. My first documentation desires are satisfied with eldoc, giving me parameter lists in my working buffer. From there I jump-to-definition to see source code and docstrings. (The one place this unfortunately doesn’t work is the Datomic API (since it is understandably closed-source), forcing repeated switches to the browser.)
The next step is to use my editor to look up extended docstrings, guides, and other short article-like writings for single functions. Grimoire is currently the vehicle I think is best to deliver this, but my doc-lookup workflow here is still in flux. I’d like to develop a way to cache their entire knowledge base locally instead of making HTTP requests on each lookup. I also satisfy this step with checking ClojureDocs in the browser.
All of those doc-lookup steps, because they are kept mostly rather brief, feel like restoring knowledge I already have, and don’t interrupt my coding too much. The next step is different. Beyond those quick reminders, I resort to looking up project READMEs and published guides and articles. This is of course a useful process but I find it more like research than a reminder. Perhaps I should stay in emacs to browse READMEs?
I have a separate documentation-exploration process when evaluating libraries, which is web-based browsing of READMEs and source code, plus checking commit recency and issue and PR triage, and trying it interactively with a REPL. I’m a big proponent of at least skimming source code to get a sense of library quality, technique, probably “gotchas”, and so on. The core namespaces are usually useful, but I also like looking at their test suite: it tells me both whether they have a robust test suite, which is an indicator of library maturity, as well as how the library API is used rather than how it is written. For seeing whether I should use a library or not, it’s one of the most useful steps.
Because my process leans on editor-based docstring lookup, I personally find browser-based API docstring sites not so useful. But I recognize their utility for other folks and therefore would like to do a better job of providing them in the libraries I maintain.
What I really appreciate is when a Clojure library provides multiple well-maintained, literate-programming-style walkthroughs of how to use their functions in both the simplest most minimal way and for progressively more convoluted tasks. These can be separate guides, namespaces, or just part of the README.