On Jan 10, 2008 5:28 AM, Charles Marcus <CMarcus@media-brokers.com> wrote:
Andrew Falanga, on 1/9/2008 6:02 PM, said the following:
What should I say? The Dovecot wiki <http://wiki.dovecot.org/> is very informative. :-)
Very informative yes, but at the same time it seems to make the same mistake all people make when writing documentation. There are many assumptions made that a lot of fundamental knowledge of how mail works is known to the reader. For example, the term "mbox" is simply used. It's not really described anywhere (admittedly, that I could find) what mbox is. It took much looking, and in fact one respondent to my question, a week ago, about what mbox and MAILDIR were, didn't respond with a dovecot wiki page but instead a wikipedia page. This really shouldn't be. This is only meant as constructive criticism, I'm not trying to be condemning here.
No offense, but that is just plain dumb. Have you ever heard of google? It took me all of 10 seconds to find more articles about these two formats than I could read in a week.
I was a little apprehensive about making this message because I thought someone would take offense to it. Yes, I have heard of Google (in fact, if you look at my address, you'll see it's a gmail account). The point I'm making is, if I'm reading from dovecot how to configure things, why would I need to "walk the world" to glean the information necessary?
Put another way, I'm not saying that whomever maintains those pages needs to completely discuss everything, but some discussion about what is being referred to is necessary. If I were to just start talking to you about something you didn't understand, you'd ask me what it is I'm talking about and would be very put off if I didn't explain myself but rather said something like, "look it up yourself." But what you've said is tantamount to just that.
If it's expected that the reader knows what the difference between mbox and MAILDIR is, then a "disclaimer" or sorts should be given at least in the opening page of the wiki. Something like, "It's assumed that the reader has more than a basic understanding of how mail systems work . . ."
Anyone who is setting up a mail server that doesn't at least have a BASIC understanding of the BASIC things that mail servers deal with maybe shouldn't be administering a mail server? Or should at LEAST spend a few weeks LEARNING the basics on their own.
I agree and I did have more than a basic understanding. Prior to becoming a programmer, I spent 11 years as a network administrator and about 1.5 years of that time was administering e-mail. However, and very unfortunate for me, the extent of my experience working with e-mail for that time was all in Windoze and Exchange. Oh, also a package from IPSWITCH, can't recall now the name, but all of the work was done for me. One of the reasons I've come to resent the Windows world.
The flip side is that how else does one gain the experience to do anything without being exposed to it? Very often I've noticed from people who know an attitude of, "Well, you shouldn't be doing this unless you have some idea of what you're doing." The problem is, without doing that thing, they can't have much of an idea of how to do it to begin with.
According to your argument, maybe I should complain that Timo didn't define the word 'is' on every page he wrote?
I'm afraid you didn't understand my argument. That could, honestly, be because I didn't articulate it correctly. Sorry.
Andy
-- A: Because it messes up the order in which people normally read text. Q: Why is it such a bad thing? A: Top-posting. Q: What is the most annoying thing on usenet and in e-mail?