On Mon, May 5, 2014 at 9:32 AM, Mars0i <marsh...@logical.net> wrote: ...
> 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. > That sounds about right to me; communication (writing) skills, mainly. Of course, my degree is in the humanities, so I would say that. Now I think of computation as a new addition to the classic liberal arts. I'm beginning to think that the Clojure documentation system may be optimal. Not "best possible", just optimal: does what it does (meets programmer needs) just well enough to survive. If it were genuinely failing us in some important way, it would be changed. -Gregg -- 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.
