[wp-docs] Task based documentation

[Michael D.Adams]

I've thought about this a bit over the past few days and really agree  
with Morgan.  In particular, it will be difficult to convince me that  
[[USER:MDAWaffe/Administration Panels]] etc. are not useful in their  
current form.

It may be possible to argue that Task Based docs are overall more  
useful, but it seems to me Tour (as Morgan aptly puts it) docs are  
necessary as well.  Documentation needs to come from both sides:

Alice asks "Can I make a particular Link not appear on my Links list?"   
TASK BASED

Bob points at his screen and asks "Links -> Add Link / Advanced:  
Visible radio button.  What does that mean and what does it let me do?"  
  TOUR BASED.

It's really the same question asked from two different ends.  Both get  
asked, and both need to be addressed.  But knowing one question does  
not mean you know how to ask the other.  Including documentation like  
[[Administration Panels]] is therefore necessary.  Where it should _go_  
and under what title (even ignoring the Panel nomenclature issue) are  
important questions, though.  Especially since it'd be nice not to  
duplicate information much (redundant and twice as hard to update).

Perhaps [[A Tour Through WordPress Administration|Administration  
Panels]] would be an appropriate link from [[Administering your blog]].

Please comment, critique, lambast or whatever else.

Michael
MDAWaffe

On Feb 21, 2005, at 1:13 PM, Morgan Doocy wrote:

> I agree that task-based articles are more frequently used. However, it  
> is also worth noting that any good reference book on an application  
> with a UI will have sections which simply describe the UI and give  
> only general overviews on how to use it, and I think we would be  
> remiss to exclude that from the Codex. It is also worth noting that  
> task-based instructions need to be updated just as much as the more  
> expository "tour" articles as the software evolves. It's my opinion  
> that both are essential to a reference, even though instructions are  
> the more frequently used.
>
> Morgan
>
> On Feb 21, 2005, at 12:31 AM, Matthew Mullenweg wrote:
>
>> Since we have this list back, let me emphasis that the best sort of  
>> thing for the codex is *task-based* documentation not  
>> structure-based. Task-based docs survive changes in the application  
>> better (menu items may move around a lot) and matches more how people  
>> use software.
>>
>> Links:
>> http://www.sprez.com/news200110.htm
>> http://www.io.com/~hcexres/tcm1603/acchtml/task_analysis.html
>> http://www.usabilityfirst.com/glossary/term_704.txl
>> http://www.techwr-l.com/techwhirl/archives/9802/techwhirl-9802 
>> -00321.html
>>
>> -- 
>> Matt Mullenweg
>>  http://photomatt.net | http://wordpress.org
>> http://pingomatic.com | http://cnet.com