[drupal-docs] Usability issues in documentation style

[Kieran Lal]

Hi, I am coming into the style guide conversation a little late and  
my comments may be considered off-topic from the style guide, so I  
have gone off thread.  The style guide conversation seemed to be  
flirting with defining usability as some quantitative measures.  i.e.  
Don't link too deep.   Let me propose some other measures to consider  
in the usability of the documentation.

1) task completion- Are users able to read the documentation and  
complete their task?(success rate)
2) time on task- How long does it take users to read the  
documentation?  This is particularly relevant when trying to come up  
with rules about short vs. long pages, and the total number of  
clicks.  Also, documentation that requires interaction with a Drupal  
site will have a big impact on time.
3) error counts- When reading the documentation and navigating  
through it do the users click the wrong links.  It is possible that  
few links, less than 4, that are confusing are less usable than lots  
of links that don't cause clicking errors.
4) post task satisfaction (the subjective rating).  When users  
completed reading the documentation were they satisfied?

Drupal documentation style needs to be more than the structure of the  
content.  It needs to be the experience of the whole page, including  
the headers, and blocks on the side.  One of the biggest complaints  
that web site designers have about CMS's is that they do not have  
complete control over the user experience.  In particular they want,  
to control the blocks and the page header.   I believe this is very  
relevant to documentation.  If you create a wonderfully structured  
document, with great usability but have a site header, surrounding  
blocks that are out of context, and don't meet the users needs for  
that page then it's not as usable as it could be.  I am frequently  
forced to read articles in print format to make them understandable  
because advertising and an over abundance of links crowd the page.  I  
have asked Chris Messina, to add the ability to turn off site headers  
to themes so that we can have more control of the experience of a  
page.  For example, see how there is no site header at http:// 
civicspacelabs.org/home.

I would like all documentation to be able to be locally stored within  
a site.   If there is a better way to get linking directly into the  
administration interface then I would be glad to use it.  But in my  
opinion the most usable documentation will be documentation that is  
interactive with a users site.   The style guide currently proposes  
linking rules.  I propose that we add a named link.  As I understand  
it you can name a window and then cause all links to occur in that  
window.  It would cause a lot of errors if the links caused the  
current page to change while users were reading documentation.  At  
the same time, we don't want a new window every time a link is  
clicked, as this would cause lots of errors from being in the wrong  
windows and increase time on sorting windows.  I don't know the exact  
syntax, but I would like it to be done consistently.

Finally, we need a way to quickly transform

www.example.com/admin/module to

<a href = "/admin/module" title = "module administration">your site's  
module administration </a>

so that documentation works well inside a site.

I acknowledge that this may fit outside the documentation style  
guide, but these ideas are important to making the documentation usable.

Cheers,
Kieran