>> TL:DR >> >> Write ideas for humans around your code or it will die. >> Explain, don't document. >> >> >Excellent post, Tim. Thanks for writing it all up. > >Though, I tend to think that "documenting" is the same as "explaining" >(what good is documentation if it doesn't explain?).
The word "explain" is semantically the same as "document" to most people but not to the programmer community. I chose the word "explain" carefully. The word "document" has negative emotional overtones for programmers. It usually implies fulfilling checklist requirements like "Does it have a Javadoc stanza?". I just gave a talk at the WriteTheDocs conference. People who do this for a living ("documentarians") were proposing creating games like "document like a pirate day" to "entice programmers to document". Personally, I see documentation as a mark of a professional. Rise to the standard or retire into management. Tim Daly Curmudgeon at Large -- -- 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/groups/opt_out.