[drupal-docs] Idea - move help text out of code into database

[Charlie Lowe]

Kieran Lal wrote:
> 
> On May 14, 2005, at 9:33 AM, Charlie Lowe wrote:
> 
>> * target audience
>>
>> * the ways in which the current text targets that audience
>>
>> * the ways in which the current text could be improved in terms of
>>
>> targeting the audience
>>
>>
> 
> Charlie,
>     Can you point me to some how-to's so I can write these for Admin 
> Help documentation?

If you want, I would be glad to help with this and developing the 
document you already created. Once it's done, then it's a great guide 
for anyone trying to revise the admin/help as well as a good starting 
point for figuring out how to do the more in depth configuration docs in 
the Drupal handbook.

But in answer to your question, do you mean howto's for doing that sort 
of analysis? The only public resource I have (there is some stuff in 
text) is this audience analysis worksheet which I use in class:

http://joe.english.purdue.edu/~lowe/f04_2/files/docs/audience_analysis.doc

Is this the kind of thing you are looking for?

I'm sure you also probably know this, Kieran, but for those that don't, 
typically the term "rhetoric" is misconstrued, associated with political 
discourse. Rhetorical analysis *is* about audience. It's about 
understanding the audience for a text and how that text is 
situated/structured for that particular audience. So I could try to 
develop something, but rhetorical analysis is pretty complex and 
encompasses lots of intertwined approaches dating back to the Sophists 
and Aristotle (including  the study of usability, for instance); a 
simple howto might not do it.

Maybe revising that list will help:

* Understanding the target audience for the documentation. The audience 
may be composed of primary and secondary audiences. Usability studies of 
previous documentation are useful in definining the audience.
* Understanding the goals for the documentation, how it is supposed to 
meet the needs for that audience, as well as in the case of the 
admin/help section, constraints on providing that documentation 
(difficulty in encoding longer texts). What is the primary focus for the 
document? Any secondary focus?
* Understanding where the original documentation meets those goals 
successfully.
* Understanding where the original documentation fails to meet those goals.
* Strategies for revising the documentation to meet it's failings while 
preserving what it does successfully (sometimes, this may include some 
tradeoffs dependent on other constraints).


Some key concepts in meeting the goals:

* Language - Is the language used accessible for the target audience?

* Style - Is the style appropriate for the particular type document and 
situation in which it will be used?

In the case of the admin/help, this would involve readbility as an 
electronic document (scanability, chunking of text, use of bullets, 
headings, emphasis, length of text, etc.), usability as a document 
within the Drupal interface (i.e., linking, appropriate use of titles by 
Drupal), common expectations of readers about the style of the 
documentation (readers bring certain litercies/familiarities with 
documentation styles; adopting and adapting those can facilitate better 
use of the documentation)

* Content - Does the document content/concepts meet the needs of the 
target audience as the goals of the document are defined? Is the content 
accurate? Does the document stay on focus (i.e., does it extraneous 
contain information which is not necessary to meet the goals of the 
target audience)?

* Structure (overlaps with style)- Does the document present the content 
in the structure most likely to provide the user with the information 
they need (in other words, most important things first necessary for the 
reader so that the reader does not become frustrated)? Does the 
structure make the document scannable for users looking for something 
rather than depending on users to read the whole text?



Charlie