We can see from this discussion that several strongly opinionated visions of what documentation should be coexist. Some want literate programming whereas others want to avoid it, some want something that looks like javadoc, some just want markdown, etc.
I think we can just make room for all of these views. Let's start by providing functionality for creating and viewing neutral, structured, extensible documentation content. I think both Markdown and raw strings are too weak for that; I'd rather make a more sophisticated language/data structure and then translate Markdown or docstrings or whatever into it. Then we can create more pleasant programmatic interfaces on top of it, to achieve the goals of simplicity and of the more opinionated paradigms. That's my reason for wanting to make this in Clojure data structures in the first place; as long as we have the benefits of Clojure's great programming features, we can mostly avoid having to make tradeoffs between available functionality and desired usage, and that's *good*. Let's not make anything opinionated mandatory or standard until usage has proven it. Also, I agree that we need better formalism and categorization for reasoning about technical documentation. Very good things were said in the Deep Thinking<https://groups.google.com/forum/?hl=fr#!searchin/clojure/deep$20thinking/clojure/YOeQVUWhUtA/f917yFk5NIoJ>thread on this topic. I see there are a few books in the field, I'll try to dig into these. Le mercredi 7 mai 2014 05:16:16 UTC+2, da...@axiom-developer.org a écrit : > > Gregg, > > I realize that literate programming isn't going to catch on in the > Clojure community any time soon. LP shared the "epiphany" feature > of Lisp. That is, you don't "get it" until the "AH HA!" moment, > and then you wonder why anyone programs any other way. You can't get > the Lisp AH HA! without writing Lisp, so many Java programmers will > never "get" Clojure. You can't get LP without writing LP, so many > programmers will never get LP. Oh well. I am trying to refocus on the > goal of "deep thinking" the documentation problem in Clojure. > > > > My more recent posts have moved on from LP and have been focused on > finding criteria to judge whether proposed solutions actually address > useful goals. Parent tried to do that in his thesis. See my prior post. > > There are many different audiences that need Clojure documentation. Some > are core maintainers who have to understand the Java code. Some are > programmers who need to understand the language. Some are library > maintainers who need to explain their use case. Some are people who join > a company using Clojure. Some are language designers who need to > understand principles like immutability, simplicity, STM, etc. > > There are thousands of useful programs in github. Most of them are > dead because the original programmers are gone and nobody knows their > use case nor how to maintain and modify them. Once the original team > moves on even popular projects die. Even programs written by famous > people with huge amounts of influence die. Witness Arc by Paul Graham, > or Pascal which took over the world in the last century. Without Rich, > wither Clojure? > > I really like Clojure and I want it to live. I believe that unless > we focus SOME effort on making it easy to maintain, modify, use, and > understand then Clojure will suffer the fate of Pascal, Arc, and that ilk. > > > > > > > To my knowledge neither > > Knuth nor anybody else has ever produced a shred of evidence in support > of > > this kind of claim. > > I can't speak to your knowledge but there are numerous examples. As to > the cited stackoverflow claim that LP is not used in projects or > teaching... > > Here is PROJECT example from SAGE, a python-based computer algebra > system in Number Theory: > > "Another thing I've been enjoying lately is literate programming. > Amazingly it turns out to be faster to write a literate program > than an ordinary program because debugging takes almost no time." > > -- Bill Hart, SAGE Mailing list, May 3, 2010 > > Here is a TEACHING example from Spring 2014: > > John Kitchin is a professor of Chemical Engineering at CMU. He is > teaching CMU students to use literate programming and uses it in all of > his courses. He recently gave a talk at PyCon > > http://www.youtube.com/watch?v=1-dUkyn_fZA > > > > > > Are you saying the core Clojure team is > rewriting > > Clojure in *classic* litprog style? That would flabber my gast, to put > it > > mildly. > > No, "the core Clojure team" is NOT rewriting Clojure in *classic* > litprog style. I am, with the help of others. See > PDF: http://daly.axiom-developer.org/clojure.pdf > SRC: http://daly.axiom-developer.org/clojure.pamphlet > > If you follow the instructions you can type 'make' which extracts > Clojure source code, compiles it, extracts and runs the test cases, > and puts you into a REPL. It also re-creates the PDF. The whole > process takes under a minute. LP is trivial to learn and use. > > The cycle is to edit the file (code or natural language), type > 'make', and your new code is built, tested, and ready to run. At > the same time the PDF of the book is recreated from the same source > so it is "up to the minute". Rinse and repeat. > > The format supports images, hyperlinks, a table of contents, an > index, a bibliography, appendicies, diagrams, audio, and video. > > The hard part is "reading the code" and trying to reverse engineer > what the core Clojure team wrote. This is code written by the best > in the business. Despite that and contrary to popular belief, reading > someone else's code is NOT easy to do. > > Tim > > > > > > > > > > > -- 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.
