[documentation] [task] Drupal core installer messages

[Jeremy]

Issue status update for 
http://drupal.org/node/51772
Post a follow up: 
http://drupal.org/project/comments/add/51772

 Project:      Documentation
 Version:      <none>
 Component:    Misc
 Category:     tasks
 Priority:     critical
 Assigned to:  Anonymous
 Reported by:  webchick
 Updated by:   Jeremy at kerneltrap.org
 Status:       active

Thanks!   I've merged your improved help texts into the latest patch
[1].
[1] http://drupal.org/node/52289




Jeremy at kerneltrap.org



Previous comments:
------------------------------------------------------------------------

Tue, 28 Feb 2006 17:12:58 +0000 : webchick

Attachment: http://drupal.org/files/issues/messages.txt (8.96 KB)

Attached is a list of error/status messages that the Drupal core
installer [2] generates. This list may be out of date by now; if so I
will post a follow-up that contains the new versions.


The idea is to make these error messages friendly and readable to
anyone who might be installing the software. The basic formula for good
error messages is:


   1. What's the problem?
   2. How do I fix the problem?
   3. How do I avoid the problem in the future? 


Here are some resources on writing good error messages I've come across
during my research:



* Error Message Guidelines [3]
* Error messages: More important to your website than you think [4]
* How to write Error Messages [5]

This is A LOT harder than it looks. :P But if you have experience
writing error messages, it would be awesome if you could lend a hand
here because we're pushing to get the installer finished ASAP. Remember
that this is the first impression people will have of Drupal, so we want
to make it as welcoming and friendly as possible.


Thank you very much.


[2] http://drupal.org/node/48732
[3] http://www.useit.com/alertbox/20010624.html
[4] http://www.marketingprofs.com/3/stoeckle1.asp
[5]
http://www.klariti.com/technical-writing/writing-error-messages.shtml




------------------------------------------------------------------------

Sat, 04 Mar 2006 16:35:19 +0000 : Jeremy at kerneltrap.org

Attachment: http://drupal.org/files/issues/messages_0.txt (2.43 KB)

Here is a smaller list of messages that should be focused on first. 
These are from the core requirements API as defined in this patch [6].
[6] http://drupal.org/node/52289




------------------------------------------------------------------------

Sun, 05 Mar 2006 16:34:22 +0000 : webchick

Attachment: http://drupal.org/files/issues/messages_0_0.txt (5.02 KB)

OK I decided to take a stab at this, since it looks like no one else is
going to. :\ From now on, I am answering any complaints in the
forum/#drupal-support about Drupal being too hard to install with a
link to this post. :P


Here's an updated messages_0.txt, where I just overwrote the old
messages with a new one. If you can continue to break up the messages
by section of the patch like that it should make it much easier to
attack these a little bit at a time.


I wasn't able to satisfy all 3 conditions above, but I did at least try
to give a little more info about what the consequences were if something
wasn't done, and how to resolve the issues. The only problem is almost
all of the ones in messages_0.txt are really out of your hands if you
either aren't savvy with web server administration tasks, or are on
shared hosting. In these situations, really the only recourse is to
contact the web server admin for help, so there is a lot of redundancy.
:\


I wasn't sure at all what to do about the following:


- Unexpected error: function "%function" does not exist.
- Unexpected error: unable to find file "%file", function "%function"
does not exist.


And on the permissions-related ones, I've added a new variable which
would need to be populated: %path. This way people could just
copy/paste the lines into their shell.


PLEASE REVIEW. These might not be totally correct/accurate, and I think
they still read way too 'technical' for most people. I'll see what I can
do about that, but this is one area where I think we really need a
"newbie's touch."