Share your documentation-lookup workflow!

[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.