Skip to content
Hallway
0:00 / 0:00

#clojure#documentation#cider

Towards Awesome Clojure Documentation – Bozhidar Batsov

Metosin

9K subscribers • 22 videos on Hallway

YouTube
  • Recommended by 1 person: 1 in engineering communities.
  • Presented by Bozhidar Batsov
  • An opinion. It argues one side of a question engineers disagree on.

Intermediate. Assumes working knowledge.

3K views9 years ago1 recommendation

Tools and practiceProgramming languagesOpen sourceLisp and ClojureCode review and teamwork

Bozhidar Batsov discusses the state of Clojure documentation, its challenges, and how the community can adopt better practices and conventions.

Most developers allegedly hate writing documentation. On the other hand, pretty much everyone considers good project documentation to be a strong indicator of the project's quality. Go figure! In this session we'll examine the state of the current documentation initiatives and practices in Clojure, some overall problems with documentation in Clojure and some potential solutions. Here's a few topics will touch upon: - the various Clojure documentation projects - the quality of the official Clojure documentation - lessons we can learn from other Lisps when it comes to documentation - adopting a common convention for structuring docstrings - additional documentation metadata Documenting things can be fun and extremely rewarding! Join us and find out how!

Why it's here

1 person recommends this

What people say. Recommended as a discussion on the shortcomings of Clojure's official documentation and how to improve it.

Moments people linked to

u/202700000000in r/Clojure • Recommends

…English teacher, I hope, otherwise we're screwed. PS: Perhaps the biggest problem is that I can't even imagine how people learnt this language before https://www.braveclojure.com/ was written. The documentation on the main Clojure website I'm sure wasn't written for humans, maybe not by a human either. PSS: /u/moxaj posted this link down below: link to this video It doesn't have as much profanity (surprisingly) but it also says a lot about the state of Clojure's documentation. Honestly it paints an even worse picture than I thought, as soon as anything Clojure-like (is there already something?) but with better documentation comes along, Clojure will basically die. That's my prediction. Unless Cloju…
84View on Reddit

u/nogridbagin r/Clojure • Mentions

On “"key work", "kewyord", and "keyword"”

Hi guys, Clojure newbie here. My last time using a lisp was a very long time ago, but I'm having fun with Clojure so far. I was a bit surprised by the lack of documentation on the main clojure.org webpage given Clojure has been out for some time. I expected the docs to be a bit more mature. I began reading some older posts and found this vid which summed up my early experience thus far: link to this video Given the main getting started guide is only 4 pages, I was surprised by the obvious spelling errors above. When I see this in code, it's usually a code smell. I'm excited about learning Clojure, but honestly this is a bit of a turnoff seeing this in the official docs.
8View on Reddit

u/moxajin r/Clojure • Mentions

On “I just started learning Clojure, I love it but the documentation is just about the worst thing ever”

Re parens: 1. As others have pointed out, clojure has roughly the same number of parens/brackets/braces as say java (it also improves upon other lisps by introducing literals for vectors, maps, etc.) 2. After a while, you'll pretty much ignore parens and focus on indentation, just like in Python. Moreover, if you use a tool like Parinfer (which I highly recommend), parens are automatically handled for you, as long as you take care of indentation. So essentially it's like Python with some additional benefits. About the docs: you are right, they are pretty bad for newcomers. See this talk.
5View on Reddit

u/ledgerdevin r/Clojure • Mentions

On “Clojure Growth Trajectory”

> Its not clear what you mean. Are you suggesting the core team isn't trying to improve the language? There are clear indications clojure is not at all healthy when compared to most other languages. This section of a presentation is a good summary of a very important aspect, documentation. link to this video
1View on Reddit

u/daveliepmannin r/Clojure • Mentions

On “Is there a place for a #documentation slack channel to coordinate and support Clojure documentation efforts?”

What kind of agreement or disagreement should we expect on docstring changes such as Bozhidar recently proposed? He proposed a broad push towards consistent notation, formatting metadata, an easier contribution process for docstrings, and more verbose explanations (particularly for namespaces).
1View on Reddit