(There are now three recent threads on documentation in the Clojure Google group*. *The other threads are "Code Genres" and "Deep Thinking". It was actually *da...@axiom-developer.org's May* 4 post in "Deep Thinking" that stimulated these remarks; I posted in this thread only because it has "documentation" in the title, so the intent is clearer, but if you're new to these discussions, you should read the other threads as well.)
A thought crystallized out of my slight discomfort with some of the remarks on documentation in this group lately. I kept thinking "I have written good documentation in the past (sometimes), when other programmers with whom I worked didn't. And we didn't have any special tools. Just text editors. Why do I need special tools for documentation?" (Of course I do think special tools for documentation can be a good thing. sometimes, but I kept having this thought all the same.) We're programmers, so it's natural to try to problems by programming. In trying to improve documentation this could involve programming in the usual sense (writing code), or programming the programmers (creating informal or more formal standards for documentation). I used to work as a professional programmer, but now I'm a professor in a humanities discipline. (I do Clojure programming as part of some of my research projects.) I think a lot about writing clearly and about teaching. For both, there are are methods, guidelines, rules of thumb, things to try out, etc., but the most important thing is to try to think through what your intended audience needs in order to understand. And in the end, there are no fixed rules. Just figure out what your readers or students need, however you do it. That's exactly what good documentation involves: Figuring out what other programmers will need when they read your code. (And figuring out how to communicate that.) I think that some of the ideas that people have been proposing in these threads are good. There are some things that it's good to do routinely, even if you aren't thinking much about the intended audience. And the right tools and conventions can help convey information more clearly. Obviously, a lot of the discussion here is already focused on thinking about needs readers of code, so in a sense I'm not saying anything new. Still, thinking about programmers I've worked with in the past, a part of me wonders whether part of what's needed is not programming (with code or rules), but also a focus on cultivation of a set of skills that are not *programming* skills per se. Good tools or rules will only get us so far. -- 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.
