On 02/10/2011 04:15 PM, Andrei Alexandrescu wrote:
- Write a separate document about dates and times in the form of a manual, and
reduce the size of the documentation proper. Insert references to the manual.
Very good solution, I guess. (but it must be done, and well done)
FWIW: once collegues and myself had to face similar doc issues (about pedagogic
material). We ended up stating the following rule: when the /domain/ a tool
addresses is problematic in itself, then write a separate guide for it. Else
write the doc for the tool itself, with the presupposition the domain is not an
issue, and people only need some hints about the tool itself. If it is properly
designed, the inline doc should be both short & simple; else, it may reveal
design issues.
I guess (just my opinion) DateTime's domain clearly calls for a separate doc:
issues on date/time counting, time zones, locale formats, etc, are all but
trivial and well-known. (And I don't even evoke other calendar systems ;-)
What do you think?
Denis
--
_________________
vita es estrany
spir.wikidot.com
_______________________________________________
phobos mailing list
[email protected]
http://lists.puremagic.com/mailman/listinfo/phobos
