[wp-docs] Structure & Priorities

[Morgan Doocy]

On Dec 13, 2004, at 3:47 PM, Matt Mullenweg wrote:

> Podz wrote:
>> - Should the docs for 1.3 follow the format of the admin menu ?
>
> I don't think so. I think the documentation should be task and 
> question based, rather than key off the current organization of the 
> menu.

My instinct would be to do the opposite, to start with the Admin menus 
and work out. I think new users (even more advanced new users) expect 
to be taken through a structure they can visualize first, and then 
proceed to the more contextual task-based instructions as they become 
familiar with the lay of the land.

I would expect the documentation site to contain: [Forgive me for using 
TLDP terms :-) ]
1. "Guides" catered to broader usages or longer processes (e.g. 
installation, ongoing administration, customization, templating, and 
regular "end-usage")
2. "HOWTOs" outlining specific instructions for smaller tasks (e.g. 
blogging by email, creating static pages)
3. An underlying structure of pages annotating and briefly describing 
every feature on the Admin menu, preferably with screenshots
4. A basic foundation of glossary terms & definitions
5. Other aggregations of data (e.g. feature lists, external reference 
links for CSS/HTML)
6. A developer reference, where all code is documented (a nice-to-have, 
probably for the distant future)

I think our priorities should be numbers 1, 2 and 3, in no particular 
order of precedence. Much of this information already exists in the 
current wiki, but I think it needs to be thoroughly restructured, 
consolidated, and edited as we bring it across to Codex.

The problem, I think, with people not finding the documentation they're 
after is as much an issue of structure & presentation as it is of gaps 
in the content. Wikis are awesome tools, but there is a level of 
professionalism that must be maintained in order for users to feel like 
it's authoritative. The main reason I find Wikipedia so outstanding is 
that so many pages have been so thoroughly and professionally reviewed 
that its users have a high level of confidence in its content. Our 
documentation must look equally professional, I think, in order for 
users to feel like they're even looking in the right spot -- much less 
feel like they can find the information they're looking for within it.

What does everyone else think? As we come up to Wiki Day, we should 
probably have a roadmap or priorities set up to guide us in the right 
direction. What do you think those priorities should be?

Morgan