On Wednesday, May 21, 2014 6:03:04 AM UTC-5, da...@axiom-developer.org
wrote:
>
> 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
> da...@axiom-developer.org <javascript:>
>
> [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.
