Hello to all,

*Short version :* I think Clojure needs a documentation system in Clojure, 
I would like to know if some efforts exist in that direction, and I am 
willing to create it / contribute to it.

*Long version :*

I've been thinking for a while that the Clojure community could benefit a 
lot from a more sophisticated and ergonomic documentation system. 

I have seen some existing plugins like lein-sphinx, but I think it would be 
really good to have documentation that would be written in Clojure, for the 
following reasons :

   - we're all very fond of Clojure data structures and their syntax. (I 
   don't know about you, but I find that even HTML looks better in 
Clojure<https://github.com/weavejester/hiccup>than in HTML). Plus, Clojure 
programmers already know how to edit them.
   - (better reason) The facts that Vars are first-class citizens and that 
   symbols can be referred explicitly with hardly any ceremony (macros) are a 
   exceptional opportunity to make smart and highly-structured documentation 
   very easily.
   - if it's in Clojure, Clojure programmers can seamlessly build *ad 
hoc*documentation functionality on top of it to suit their own particular needs.

I haven't found anything of the like yet, and if it exists, I would be 
grateful if someone would redirect me to it.

Here are *my thoughts on this :*

   1. Clojure doc-strings, although they are quite handy as reminders and 
   for doc-indexation, are *too raw a content*. Even when they are done 
   right, they tend to be cumbersome, and it's too bad to have such concise 
   code drown in the middle of so much documentation. What's more, I believe 
   that when programmers program a function (or anything), they tend to think 
   more about the implementation than the (uninformed) usage, so they have 
   little incentive to make it right.
   2. Building on 1. having a system where documentation and programs live 
   in separate files, in the same way as tests, would enforce a healthy 
   separation of concerns. Importantly, it would make life much easier on the 
   Version Control perspective.
   3. Documentation should probably be made differently than what people 
   have got accustomed to by classical languages. Because you seldom find 
   types, and because IMHO Clojure programs are formed more by factoring out 
   recurring mechanisms in code than from implementing intellectual 
   abstractions, the relevant concepts tend not to be obvious in the code. 
   Since in Clojure we program with verbs, not 
nouns<http://steve-yegge.blogspot.fr/2006/03/execution-in-kingdom-of-nouns.html>,
 
   I think *documentation is best made by example*.
   4. Documentation of a Var should not be a formal description of what it 
   is and what it does with some cryptically-named variables. *Every bit of 
   documentation should be a micro-tutorial*. Emphasis should be put on 
   usage, examples, tips, pitfalls, howtos.
   5. There should be structure in the documentation, and it shouldn't be 
   just :see-also links - *there should be semantics* in it.  For example, 
   some functions/macros are really meant to be nothing but shorthands for 
   calling other functions : that kind of relationship should be explicitly 
   documented.
   6. Documentation should not be just information about each separate Var 
   in a namespace. There should be a hierarchy to make the most useful 
   elements of an API more obvious. Also, adding cross-vars documentation 
   elements such as tags and topics could make it easier to navigate and 
   understand.
   7. *Documentation in the REPL is great*, it was one of the very good 
   surprises when I started learning Clojure. However, a rich and good-looking 
   presentation like in Javadocs would be welcome too.
   
Of course, all of the above are just vague principles. Here is *some 
functionality I suggest for a start :*

   1. Documentation content elements could be written in a Clojure DSL 
   emulating some kind of docbook-like markup language.
   2. On the user side, the documentation would be accessible through a 
   generated web interface, a REPL interface, and maybe other formats like 
   Wiki.
   3. Documentation could be programmed anywhere in a project by simply 
   referring to the relevant Vars and calling the documentation API. Ideally, 
   there would be a dedicated folder for documentation files, and a Leiningen 
   plugin to compile them and generate the HTML from them.
   4. I often find myself lost because I have no idea what shape some 
   arguments to a function should have, such as config maps and maps 
   representing application-specific models. To adress this, I propose to 
   explicitly declare and describe *"stereotypes"* in the documentation. 
   Such stereotypes could be, for instance, "JDBC connection" or "Ring 
   middleware". From what I have seen, some good 
work<https://github.com/prismatic/schema>has already been done in that 
direction, but it would be good to make room 
   for it in documentation.
   5. Weigh the documentation contents by importance, to allow for 
   displaying the documentation with several levels of details.
   6. Cross-vars, semantic documentation with *topics*, *tags*, and *links*. 
   *Topics* would group several API elements together to explain a 
   technique or concept; they could have a :prerequisite relationship to 
   help the reader navigate them. I imagine *tags* giving hints on various 
   aspects of a Var, such as :curried for a function, or :utility, or 
   :use-with-caution, etc. *Links* could be such things as the famous 
   :see-also, but could also represent more precise relationships, such as 
   :calls-to, :often-used-with, :similar-to, etc.
   7. In addition to small, Var-specific, self-contained code samples, 
   there could be larger examples (e.g sample applications), and pointers from 
   the documentation to specific points in these examples.
   8. There could be other types of documentation than just static 
   description, such as exercises, koans, quizzes, etc.

I would like to know what work has already been done in that direction, and 
if you agree that this is useful, I am willing to help design and implement 
it.

Your reactions are very welcome.


Bests,

Valentin Waeselynck.


-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Reply via email to