[wp-docs] Leveraging the Structure

[Chris Waigl]

On Tue, 14 Dec 2004 12:27:26 +0000, Podz <podz at tamba2.org.uk> wrote:
> If we take a WP task as one element that needs to be covered, and we
> then break it down (and the page using nametags) into at least 3 elements:
> - basic info
> - more advanced info
> - questions

I see that several of us are thinking in similar directions, which is
an excellent thing. There are also several drafts of "Codex
structure"/"Main index" pages linked from Codex contributors' personal
pages, so the question has been bubbling under the surface for some
time.

I'd still suggest that we do this a little differently from what
you're exploring here. For a user who comes to look at the doc, a
"task" is something often quite small (but sizes vary). In the order
of user familiarity with WP and, in general, CMS use, it could be (for
the general task of "posting"):
- how do I get an entry posted (at all) 
- how can I put an image inside a post
- how can I use quicktags
- I want to understand all these confusing options in the post interface
- how can I post code
- grrr, my characters are all messed up
- grrr, my post doesn't have a date
- how can I put a snippet of PHP inside a post and have the code executed.

This is why I suggested that not an individual page, but the entire
structure of Codex be organised according to "subsections". The first
"task" would be listed under "Basics", two through five in "Working
with WP", six and seven in "Questions and Troubleshooting", and the
last one in "Advanced topics".

You suggested to use prefixes... What would the advantage of them be?
(Generally, having no subpages is a good thing and doesn't preclude
organising existing pages into sections on an index page).

One helpful point about prefixes/namespaces would be that if you write
an entry for a particular subsection, you are invited to adapt your
language to the user skill level this section is written for.

On the other thread you suggested: 

>WPB: basics
>WPW: working
>WPT: troubleshooting
>WPA: advanced

I'm coming to think that maybe (or maybe not), we'd need another
section between "basics" and "working": "getting started".

WPB: basics. Directed at: a) total newbies b) people (even experienced
ones) who consider moving to WP and want quick overview pages about
features/licensing. Should contain no "how to" pages. Contains the
glossary. Everything except the technical overview and the changelog
should be written without unexplained technical terms
WPS: getting started. Directed at: everyone who wants to set up WP.
Detailed "before you install" and "installation" sections. Very gentle
sections on how to post, what registered users can do, what visitors
can do, how WP works, and what the files you can change are.
WPW: working with WP. All kinds of task-oriented instructions. Pages
should be short and heavily linked to basic/troubleshooting/more
in-depth pages. Supposes that users have read the relevant info in the
"getting started" section.
WPT: troubleshooting. Complexity of the explanation should match
complexity of the tasks the trouble arises for. So eg the installation
troubleshooting section should be gentle (as it is!), the page on
setting up WP on some exotic architecture can be more technical.
WPA: advanced topics. Presupposes familiarity with the relevant WPW
articles and thus can build on what is explained there.
 
> So the one 'Post' page has all the info.

[snipping wildly]
There's just too much info on posting for one page, I fear. And for
some of what you list (like messed up characters) I, as a doc user,
wouldn't look on a general "posting" page.

> The task falls apart here because of the Category - that isn't a task as
> such, it's just /there/. So we would need a page just for the Category ?
> Even though it isn't a task ?

The task is "how do I assign posts to categories" (including: creating
categories, subcategories...). Another, advanced, task is "how can i
show/hide posts from one or several categories". Another, less
advanced but still advanced (or maybe not quite): "how do I move posts
from one category to another / delete a category". ...

[more snipping]
> Will pages get to unmanageably long ? Some might I guess, depends again
> on how we break things down.

They would like this, I fear. But they wouldn't if pages are organised
according to skill levels required for a task (or skill levels at
which a particular task is likely to sent users to the doc).

-- 

Chris Waigl
blog: http://serendipity.lascribe.net/ 
experiments: http://chrysalidesque.f2o.org