Share your documentation-lookup workflow!

[dave.liepmann]

From the success of Share the nitty-gritty details of your Clojure workflow! and talking to @martinklepsch and @plexus about their efforts to raise the default level of Clojure libraries’ documentation, it occurred to me that we could use a similar workflow-sharing session focused on documentation

What is your process when you encounter a function that you don’t recognize? What is your preferred method of exploring documentation for clojure.core and Clojure libraries? Some folks stick to reading the source in their editor on GitHub, some folks rely on Grimoire via CIDER or some other method, some of us seem to always have a tab open to clojuredocs.org. To jog your memory, here’s a check-all-that-apply poll:

• Editor-integrated doc lookup (like in CIDER or Cursive)
• Documentation browsing apps (like Dash)
• Generated docs (e.g. codox)
• Project READMEs via web
• Project source via web
• Grimoire via API
• Grimoire via web (conj.io)
• Clojuredocs.org
• Other

Show results

(My sincere apologies if I omitted your favorite option or your documentation-sharing resource!)

But don’t restrict yourself to the poll! What is your ideal—what do you wish every Clojure library author did to document their project? What kinds of guides and tutorials do you find most helpful?

People in the Clojure community are working as we speak on projects to improve the documentation landscape, so voicing your preferences could shape the decisions they make to better serve your use case. Plus, it helps new programmers develop their own workflow to hear how you do things.

[martinklepsch]

I’m a huge fan of using a separate app (I’m using Dash) for browsing documentation. I’ll try to elaborate a bit why that is…

• It works for almost every language with zero setup in 99% of cases
• It is not coupled to my editor — which I may not be able to use (hi, Xcode ) or simply change

In general when choosing tools I try to balance two things: how long/much will I use it and how much effort is required to reach a productive level of familiarity. Even if Dash disappears I’m optimistic that I will be able to maintain the workflows I got used to.

In many ways Dash feels like a tool that follows the UNIX philosophy of doing one thing well.

PS. If you’re on Windows or Linux Zeal seems to be the most popular documentation browsing tool.

[martinklepsch]

@dave.liepmann

What is your process when you encounter a function that you don’t recognize? What is your preferred method of exploring documentation for clojure.core and Clojure libraries?

Language documentation (i.e. clojure.core) is integrated with Dash.

For most other stuff I end up looking at these in order:

1. Project’s README
2. API documentation site provided by the library authors (often Codox)
3. or it’s source on Github.

@dave.liepmann

But don’t restrict yourself to the poll! What is your ideal—what do you wish every Clojure library author did to document their project? What kinds of guides and tutorials do you find most helpful?

I find a good Readme or “Quickstart” document of sorts very important to get starting and that certainly is a big factor in deciding whether I will use or not use a library. A good Readme for me means:

• It describes why the library was created (aka Rationale) this may include comparisons to existing libraries
• It lists features that the library provides & has usage examples for the most commonly used ones

Once I have reached some level of comfort with a library API documentation becomes more important. Reading the source of a library can replace API documentation to some degree but I think the effort required is higher compared to browsing an API documentation page as generated by Codox.

As already discussed in other threads I believe a central documentation website in the style of hexdocs.pm that combines documentation articles and API docs could provide a lot of value to the Clojure community.

[Webdev_Tory]

I feel remiss for not digging into Grimoire before now, but I am an emacs user and so use M-. for most of my lookups, as well as company pop-ups for documentation and finally looking things up on clojuredocs. I also try to figure out as much as I can interactively rather than looking it up, at least in the case of simple/core functions.

[DjebbZ]

@dave.liepmann

What is your ideal—what do you wish every Clojure library author did to document their project?

A Klipse based tutorial (when applicable).

[jballanc]

Personally, I like to stay in the REPL (or a REPL connected editor) as much as possible, which means that most of the time I end up using (doc ...) and/or (find-doc #"..."). Of course, that only helps if libraries include doc-strings that are helpful and informative enough to deduce proper usage.

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. Don’t get me wrong, Grimore is great, but for many of the more complicated libraries that I’ve run across, typically they have very nice documentation/tutorial sites, but I have to: a.) find them and, b.) keep them open in a browser tab. It would be much nicer if running (doc foo.bar.awesome-lib/complex-function) displayed the doc-string followed by something like: Enter (more-docs) to open this library's online documentation.

[dave.liepmann]

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.

[ska352]

Add to other: View source in JAR (by M-.'ing on a function in Emacs/CIDER)

[dave.liepmann]

I guess I meant for “Editor-integrated doc lookup (like in CIDER or Cursive)” to cover that case, but I mis-phrased it. Perhaps if I changed it to “Editor-integrated doc or source lookup (like in CIDER or Cursive)”?

[ska352]

Ah,

I thought you wanted to distinguish between doc and source lookup. That’s why I added it separately.

Whatever you think is best

stefan

[plexus]

@dave.liepmann

But don’t restrict yourself to the poll! What is your ideal—what do you wish every Clojure library author did to document their project? What kinds of guides and tutorials do you find most helpful?

When I first look at a library I want to find

• a brief introduction (what is it? it’s surprising how many projects miss this)
• dependency information that I can copy paste
• a self-contained example that I can copy into a buffer and play with
• API docs (e.g. codox, in html)

This is the bare minimum. What I ideally like to see as well:

• a design / rationale document. why does this library exist, with which constraints is it written, what prior art is it inspired by, how does it compare to alternatives
• a tutorial / walkthrough. Hold my hand and explain me the main concepts and functions step by step
• an actual manual, something with sections and subsections, something that I can sit down for and read through end to end if I really want to grok this whole thing. or that I can grep in when looking for specific things.

[DjebbZ]

@plexus you’re spot on. What’s often missing for visual projects is screenshots/animated gifs/videos. It’s crazy that you’re supposed to know how it looks by reading the Readme or the code…

[jackrusher]

Could you expand a bit on your use of and preference for HTML API docs?

[anthontaylor]

I feel like Dash is one of those things where you don’t realize what you’re missing out on until you actually use it. I had a co-worker that I used to pair with that would use dash all the time, so I finally gave it a shot and now I can’t imagine developing without it.

[plexus]

@jackrusher

Could you expand a bit on your use of and preference for HTML API docs?

I think it all started with the Java SE docs in the early 2000’s. I bloody loved those docs. They’re still an example for me for How To Do It Right. I always had a copy downloaded on my machine.

The big thing with those is that every package or class (think namespace) has a big chunk of top-level documentation (think namespace doc string), which taught you pretty much everything you had to know. some examples of what I mean.

For Clojure libraries I still like HTML api docs because they give me an overview of what’s in the package. I can see at a glance which namespaces are there, I can see from the front page which ones contain a single var and which ones contain dozens. When I know a namespace probably has the function I’m looking for I can do a text search on the page.

I prefer this for initial exploration over digging through the source because it’s higher signal to noise, again, you get a better overview. Once I get more familiar with the API I’ll look up individual docstrings in my editor more.

[didibus]

I find the doc string shown by my editor/ide is enough most of the time. If I still don’t understand, clojuredocs examples and notes are a life saver. I also like there Also see… links when I’m not sure what I need.

I wish editors integrated with clojuredocs to show examples and notes.

[jballanc]

I agree: Dash is amazing. One thing that I enjoy in particular is that it’s not just the core documentation for languages that’s available from Dash, but also documentation for libraries…for some languages. Got a RubyGem you need to look up the docs for? Awesome! A JAR? Great! A Clojar? Uh…

I realize it’s probably not the highest impact thing that we could do as a community to improve the documentation situation, but I’d love to see a standardize a way to distribute documentation for Coljars such that they could then be included in Dash.

(Since I haven’t had an opportunity to use any Dash-alikes on Windows or Linux, maybe someone else knows: are the RubyGem/JAR/etc. doc sets from Dash available for those tools as well?)

[jackrusher]

Thanks!

Here’s an example of what I think of as good documentation. That is, it’s essentially a book-like explanation of the software. I never feel like I’m getting much out of automatic API documentation relative to docstrings/jump to source, but I definitely do feel it when there’s a decent-sized collection of examples, some more general discussion of the software and – best case – it has sections about things like the philosophy of the package.

Unfortunately, it’s difficult and time consuming to produce this sort of thing, keep it updated, and so on, and there’s no way to automate away that effort.

[plexus]

@jackrusher

Here’s an example of what I think of as good documentation. That is, it’s essentially a book-like explanation of the software.

Yup, that’s what I meant with “a manual”. I’m trying to think which projects in the Clojure space really have that… CIDER comes to mind. Datomic’s manual suffers from the same curtness that Clojure’s official docs suffer from, and its internal organization could be better, but it’s fairly comprehensive. You can sit down and read through it and know most of what you need to know.

The yada manual is good, and bonus points for being available as an ebook/pdf. Juxt projects in general seem fairly well documented. For instance bidi only has a README, but it contains everything you need to know, including a rationale and comparison with other libs, an introductory tutorial, and manual-like sections.

[pianostringquartet]

If I’m curious about a particular function or form, my documentation-lookup workflow begins with a Google Search on that function/form.

Usually a clojuredocs.org page is enough, but I do appreciate that a Google search often brings up interesting and relevant blog posts or Github gists that go into more detail about a function or a Clojure concept. For example, I’ve used and returned to Jay Field’s discussion of destructuring often.

When I want to see all the available functions at a glance, e.g. “What can I do with a set in Clojure?”, then I use Clojure and Clojurescript cheatsheets.

I’d also like to setup offline docs, since when traveling I need documentation but don’t have internet.