[wp-docs] New WordPress Handbook

[Jane Wells]

From: "Alex Hempton-Smith" <hempsworth at googlemail.com>
> Does that mean the manual will actually be outputted on relevant  
> pages in that 'Help' dropdown?

--Yes, that was part of the idea behind the help tab.



From: Austin Matzko <if.website at gmail.com>
I'm trying to understand the problems that will be solved by creating  
a Subversion-controlled manual.  The practical realities that make  
Subversion such a helpful tool for software development are either  
not present or already addressed with a wiki.

--I think there are a few benefits. Wikis aren't set up for the kind  
of navigation that the handbook could have. A lot of people find the  
Codex overwhelming and think it's hard to find things. Outdated  
information isn't marked as outdated until someone goes in and  
manually identifies it as relating to an earlier version. With a  
Subversion controlled manual, there could be a new copy with each  
release that is easier to bring up to date. (Ever tried to go through  
every Codex page? It is a major pain because of the way wikis are  
structured.) Sometimes I come across Codex pages that have been cut  
and pasted from others to take advantage of repeat information, but  
the paster forgot to do the small edits necessary to the pasted text,  
and the Codex page would actually be incorrect. A patch system would  
make it easier for an editorial team/technical writer/whomever to  
proofread submissions before they go live, identify duplicate  
content, etc. That instant change on the wiki is great when the info  
is accurate, but what about if it's a little bit off, poorly written,  
or ignores an already written explanation elsewhere in the Codex that  
the new contributor just didn't know about because of the way wiki  
navigation is structured? It's hard to keep tabs on everything in a  
wiki.

Also, as Lorelle mentioned, the Handbook is really meant to be more  
like the owner's manual for your camera or iPhone... get you enough  
information to get up and running and do basic troubleshooting, but  
not so much that it would overwhelm with technical details that  
mostly are useful to more advanced users.


Jane