Wednesday, May 02, 2007
Advice to a new user, most open-source projects' web sites suck
One of my users got stuck trying to add a calendar to his new Drupal site. He has no idea what to do next, and doesn't even know how to ask.
I got your mesaage, but I didn't know where you got stuck or what you wanted me to do, so I left it for later.
One of the things you will pick up about open source is how to ask questions. You have to say exactly what you are trying to do, what you did, what you expected would happen, and what happened instead. Nobody can do much for you without that information. If you are asking about a possible bug, the maintainers need enough information to reproduce it. If you are asking "what do I do next" we need to know exactly what you're trying to do, how far you got, and what you are missing before you can proceed.
The chronic problem with open source documentation, and software documentation in general, is it is written by the only people who do not need it, and they have no idea when they left something out. When I looked at the Drupal site, for example, I needed an introductory overview and a glossary of Drupal jargon. But they jump right in to details of how to do this or that, assuming you already know what is in their heads. Sourceforge "project pages" are especially bad that way. The Apache and PostgreSQL sites show that it doesn't have to be that way.
Many open source sites open with a front page blog of "news" where the developers are talking to each other about details of what they did yesterday, and you have to "drill" and search for any instructions or even a statement of what the product does. Sometimes the developers just have poor English composition skills and they are unable to write a sentence saying what the thing is. Slashcode and PHP are like that. What the hell is Slashcode? We don't know how to answer that question in plain English, but here's how to join the developers' mailing list. That's just how things are and you have to get used to it.
You said "modules that need database configuration and installed software from drupal." As far as I know, each Drupal site on the server only needs one
database. Ours is the "default" site, and its MySQL account has the privileges called for in the install instructions. Does the calendar require a second database? Does it need to be told where the existing database is? Are you using a different one than the one I pulled in? I could not find any other third-party modules. In fact I had to create the sites/default/modules directory to put calendar in it.
I got your mesaage, but I didn't know where you got stuck or what you wanted me to do, so I left it for later.
One of the things you will pick up about open source is how to ask questions. You have to say exactly what you are trying to do, what you did, what you expected would happen, and what happened instead. Nobody can do much for you without that information. If you are asking about a possible bug, the maintainers need enough information to reproduce it. If you are asking "what do I do next" we need to know exactly what you're trying to do, how far you got, and what you are missing before you can proceed.
The chronic problem with open source documentation, and software documentation in general, is it is written by the only people who do not need it, and they have no idea when they left something out. When I looked at the Drupal site, for example, I needed an introductory overview and a glossary of Drupal jargon. But they jump right in to details of how to do this or that, assuming you already know what is in their heads. Sourceforge "project pages" are especially bad that way. The Apache and PostgreSQL sites show that it doesn't have to be that way.
Many open source sites open with a front page blog of "news" where the developers are talking to each other about details of what they did yesterday, and you have to "drill" and search for any instructions or even a statement of what the product does. Sometimes the developers just have poor English composition skills and they are unable to write a sentence saying what the thing is. Slashcode and PHP are like that. What the hell is Slashcode? We don't know how to answer that question in plain English, but here's how to join the developers' mailing list. That's just how things are and you have to get used to it.
You said "modules that need database configuration and installed software from drupal." As far as I know, each Drupal site on the server only needs one
database. Ours is the "default" site, and its MySQL account has the privileges called for in the install instructions. Does the calendar require a second database? Does it need to be told where the existing database is? Are you using a different one than the one I pulled in? I could not find any other third-party modules. In fact I had to create the sites/default/modules directory to put calendar in it.
> let me know if there is anything I need to do
Please turn off the HTML in your messages from Hotmail. They're really hard to read.
# posted by 0.3E9m/s @ 9:50 AM 
