[wp-docs] WP Docs, the wiki, and a goat

[Matt Mullenweg]

Podz wrote:

> Part of the problem 1:
> There is information all over the place, not limited to the wiki(s), the 
> faq, the forums, personal pages and random bits of knowledge that we all 
> have but which may not be written down because it's so 'bitty'.

Very true.

> Part of the problem 2:
> The wiki can be a confusing place for someone just looking for help 
> there-and-then. If you are a curious person like me, then I'll wander 
> round it just to see what is there, others may only go there when they 
> are confused already, and it could add to their confusion and reinforce 
> the mistaken view that you need to be able to code to use WP. (This 
> notion still persists, and we need to act postively to dispel it).

The old wiki was very much like this, due in part to the way it was 
undertaken and the underlying software, hence the Codex initiative. Any 
sufficiently advanced content management system is virtually 
indistinguishable from a good wiki. What makes a good wiki? Not looking 
*anything* like the crappy wiki.wordpress.org one. It needs things normal 
web pages have, like navigation, images, etc. This is very doable with 
Codex, and the direct inspiration is the Wikipedia. We can make the Codex 
at least as navigable (and certainly more searchable) as any other 
documentation we have, on or off wordpress.org.

> Part of the problem 5:
> Credits (possibly).

I'm open to improving this in any way possible, short of doing a pop-under 
of the authors page when their documentation is loaded. ;)

> 1 or 2 people to lead specifically this part. No more. 1 or 2 people 
> will lead, any more and people start wandering. We need it leading.
> Two is better than one - spreads the load, allows for little discussions 
> between them. Three or more - no no :)

I think this crucial step could be improved. Instead of giving one or two 
people the very daunting task of making sense of the hundreds of 
documentation pages out there, I think we should do what we do with WP 
core development: give people ownership of one specific part of the whole. 
Let's say Moose is the Links guy, and he learns everything he possibly can 
  about WordPress' links functionality and takes complete control of that 
part of the documentation. All changes and suggestions go to and through him.

So the next action item there would be identifying a logical way to divide 
up the documentation.

I am suggesting this before anything else simply because there have been 
no less than half a dozen attempts to do *exactly* what you are describing 
and not one has come to fruition. (See also, various WP Manual attempts.) 
This is not due at all to the fault of the people involved, simply that 
the task was too big, and I think dividing the problem into managable 
chunks would make this something we can finish this time.

 > <snip />

So basically I agree with the rest of the email, but that this should be 
done on a section level rather than an entire wiki/documentation level. 
This allows for more people to particpate in the process and easily see 
where help is needed (unclaimed sections). It addresses the credit issue. 
When you own a page you can subscribe to it and receive any changes via 
email, like keeping up with the comments on your blog.

Why keep it on the wiki instead of separate webpages?

* Versioning (very important!)
* Easier to interlink
* Transparency
* Searchable (also very important, think how the old wiki is tied into the 
forums search)

The only disadvantage I could think of is you'd have to learn some basic 
mediawiki syntax, but that isn't very hard at all and you can still use 
HTML if you want to in pages. Wikis do have a learning curve for contributors.

The hard part is deciding how to divide things up, however on the bright 
side the resulting structure would make an excellent base for the 
navigation system.

Codex now allows uploading of pictures of goats (or other things like 
screenshots). We can also embed other media like audio, we just need to 
think of a good use for it.

-- 
Matt Mullenweg
  http://photomatt.net | http://wordpress.org
http://pingomatic.com | more soon...