>> 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 [email protected]
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
[email protected]
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 [email protected].
For more options, visit https://groups.google.com/groups/opt_out.
