On Sat, May 5, 2012 at 9:04 PM, Peng Yu <pengyu...@gmail.com> wrote: > I agree that people have different opinions on issues like this. But I > think that "The Customer Is God". Readers of the doc is the customers, > the writers of the doc is the producers. The opinion of customers > should carry more weight than producers.
Nah, the customer's not God, and I have proof. http://notalwaysright.com/ Oops, now everyone's off reading funny stories about stupid/abusive customers. Well, when you're all back... The reason you're reading documentation is to learn. You're not handing over wads of cash and saying "Do stuff for me"; you're reading the Player's Handbook and learning which dice to roll when. Perhaps there's some jargon that you don't understand; in that case, either a FAQ/glossary or a forum post will set you straight. But if the doc says that something can't be relied upon, then there's nothing more to write there. Documentation that takes ten pages to say something is just as bad as documentation that leaves stuff out, because it's almost guaranteed that it won't be read. ChrisA -- http://mail.python.org/mailman/listinfo/python-list