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.
