[drupal-docs] We need a much better INSTALL.txt

[Kieran Lal]

Hi, here was the CivicSpace upgrade process.  http:// 
civicspacelabs.org/home/oldupgrade.  We just completed a re-design of  
this documentation here:http://civicspacelabs.org/home/upgrade.  I  
made sure to capture the Information Architecture design steps we  
used here: http://civicspacelabs.org/home/node/13478.  Farsheed, from  
CivicSpace labs and Drupalart.org and I redesigned the upgrade  
documentation based on Peter Van Djick's book Information  
Architecture for Designers.   Despite some difficulties, we have  
started to receive good feedback on the new documentation based on  
our latest release that came out Friday.

I'll detail the steps here and you can look at the work products we  
have generated so far:http://civicspacelabs.org/home/node/13478
Audience Research

     * Interviews- We posted and have conducted 5 phone interviews so  
far.  Some were general discussions and some were listening as the  
users tried to upgrade.
     * User persona-We were sure to get novice users as well as experts.
     * User goals- Still working on this.

Task analysis

     * Tasks and sub-tasks-  We used http://civicspacelabs.org/home/ 
oldupgrade as a list of very detailed sub-tasks.  Two other efforts  
on Drupalart.org and a GUI client and FTP version of oldupgrade were  
used to generate a list of subtasks
     * Non-obvious tasks- Most of this was captured in oldupgrade
     * Tasks by importance-  This was very important and we rank 20  
of the tasks and gave them numbers 1to 10, with 1 being the most  
important.

Information Architecture

     * Site map-  We chose to put this structure up right away on our  
site, rather than make a diagram.
     * Content table- This was important in developing user friendly  
labels for each of the steps, as well as agreeing what steps had to  
be emphasized.  In our case we focused on Basic Steps.
     * Flow Chart:new, old - Once the basic tasks and subtasks were  
done we developed flow charts to capture the flow and show alternate  
flows we wanted the users to go through.
     * Intro to Upgrading Landing Page-
     * Basic Upgrade instructions
     * Scenario
     * Main pages mapping to core tasks - We agreed the most  
important steps had to be highlighted on the main page and the most  
direct path focused on getting users to the most important tasks,  in  
this case our basic steps.
     * Functional descriptions- In the content table we  made a list  
of user friendly labels, content descriptions for each page, and  
tried to list the actions the website would be taking.

User testing

     * phone interviews-  Once we had a draft earlier this week we  
started soliciting users for phone interviews and many obvious things  
became apparent.  For example, our first interview with a developer  
pointed out that we hadn't included instructions to the Drupal  
handbook for upgrading custom modules to 4.6.  Also, our FAQ link  
needed to link directly to upgrade, not just our FAQ taxonomy page.
     * screen captures
     * live user testing- Once we get stable with phone interviews we  
will do some live users testing.

If someone is up for it, we would be happy to help do a similar  
process targeted at absolute new users.

Cheers,
Kieran



On Jul 30, 2005, at 7:51 PM, Morbus Iff wrote:

>> [23:06] <XXXX> i uploaded the database.mysql.inc to my database
>> [23:06] <XXXX> and it says there's an error in the syntax
>> we need a better INSTALL.txt, I tell you. (for privacy reasons, I  
>> deleted
>>
>
> This is no fault of the INSTALL.txt - it
> doesn't mention the database.mysql.inc at all.
>
> The reader is obviously confused over:
>
>    If you use a web-based control panel, you should be able
>    to upload the file 'database.mysql' from Drupal's 'database'
>    directory and run it directly as SQL commands.
>
> -- 
> Morbus Iff ( IGNORANCE IS BLISS, AND WE ARE BLISSED OFF )
> Technical: http://www.oreillynet.com/pub/au/779
> Culture: http://www.disobey.com/ and http://www.gamegrene.com/
> icq: 2927491 / aim: akaMorbus / yahoo: morbus_iff / jabber.org: morbus
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://drupal3.drupal.org/pipermail/documentation/attachments/20050731/c5a0f59c/attachment.htm