The primary focus of a "documentation system" is communication from the author to the audience.
One of the struggles apparent in discussing issues of communication, especially with programmers, is Heideggers "present-at-hand" vs "breaking down". Programmers write programs to instruct a machine to perform some task. In the ideal, this involves "communication" from the mind of the programmer to the "execution of the program". If the program works the first time it is all a seamless entity ("present-at-hand"). When the program fails, by compiler errors, missing libraries, runtime errors, design errors, inappropriate actions, or any of the other dragons of programming, the process is not seamless. The details of the process rise to our awareness ("breaking down"). The burden of failure is likely to fall on people who use or maintain the program rather than the authors. If the program survives, these are likely audiences. Programmers, generalizing from my own case, rarely have a seamless experience. Programs that work the first time, are correct, efficient, and all of the other properties, are rather far outside our experience. The effect of this constant "breaking down" is that we have learned, rather painfully, to be aware of the machinery of the process at every step of the way. This focus on the machinery becomes the expected way of communicating with the machine. Scratch any programmer, interview at any company, listen to any talk, and you find "machinery". But communication from the author to the audience is the underlying theme of literate programming. Knuth's point is about communication, not about the machinery of communication. The question is, to what audience, not how. Discussions seem to get lost in a debate about the machinery rather than the goal. We focus our debate on docstrings versus markup versus wiki. We consider literate programming to be "too much machinery". In these forums there is rarely find any example of "present-at-hand" issues of communication. That is, given a large program (e.g. Axiom, Clojure), what is it that we need to communicate, to what audience, and at what level of detail? Axiom focuses on "The 30 year horizon" under the assumption that the computational mathematics will be forever valid and that the audience will be unable to contact the likely-dead authors. Pharr and Humphreys' "Physically Base Rendering" [0] is written as a literate program, a book that won an Academy Award, using Tex and C++. The very first thing they mention in the preface is the "Audience". They communicate to humans and, also, to machines. What is the audience for Clojure? Common Lisp has achieved a long-term horizon by raising the language to a standard. No standard is perfect but it does make it possible to construct programs which have a stable base for communication. That base makes it possible to write a book like "Lisp in Small Pieces" [1] which communicates ideas in natural language using an embedded program as a reduction to practice. So the fundamental point is what to communicate to what audience, not how to implement it. Different audiences will need different implementations (e.g. docstrings for REPL users) but we must avoid losing ourselves in the noise. Axiom, by choice, has a defined audience. Does Clojure? Tim Daly d...@axiom-developer.org [0] Pharr, Matt; Humphreys, Greg Physically Based Rendering ISBN 978-0-12-375079-2 [1] Queinnec, Christian Lisp in Small Pieces ISBN 978-0521545662 -- 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.