[wp-docs] New WordPress Handbook

[Jacob Santos]

The Manual is a concise, detailed explanation with a limited and defined 
set of topics. The Codex is a guide, which consists of topics which 
range from anything and everything, which are in some areas easy to find 
and others more difficult to find. The problem with the Codex, which the 
Manual will solve is that some topics have a lot of information and 
others have none or stub amount of information. In theory, the Manual 
will contain enough information to understand the concept and work off 
of it, but doesn't mean that it will contain all knowledge on that topic.

Therefore, the Manual will contain more concise, detailed information 
that pinpoint problem and solutions with the explanation with the topics 
it covers. The edge cases, will have to be covered on the Codex.

That is how I would see the Manual, if I were to write it. Also, look at 
the OpenX ad Manual system and what it contains vs what the Codex 
contains. In some areas, the information is a lot and covers what you 
need, but I've found that there are several areas where the information 
given is not enough or accurate enough, which the Codex would be better 
to explain.

Jacob Santos

Austin Matzko wrote:
>> The WordPress Handbooks will not be in wiki form. They will be created using
>> Subversion. An example is the http://svnbook.red-bean.com/ Version Control
>> with Subversion by Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael
>> Pilato.
>>     
>
> 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.  So for example, if the
> Codex were overwhelmed by ideologues trying to reshape the Codex, or
> if vandalism were a constant problem, then I could understand
> tightening up control.
>
> If the issue is a matter having professionals generate the content,
> why not unleash those professional writers on the Codex?  The Codex
> quality will improve all around, as you'd be combining the work of the
> paid writers and volunteers who for the most part seem to know their
> stuff.
>
>   
>> The writing style will be different from the Codex in keeping with a basic manual rather than a guide.
>>     
>
> In practice the distinction between a "manual" and a "guide" is a very
> fine line, one crossed in many places already in the Codex.  If that
> distinction is the main issue, why not just supplement the Codex with
> a "manual" section?
>
> I'm concerned that this manual will have the effect of undermining the
> perceived value of the Codex, which will mean fewer people will
> consult it, and fewer volunteers will contribute both to the Codex and
> to the manual (with its higher barrier of entry).  Of course,
> potential deficits like that might be worthwhile in light of the
> overall benefit, but I'm having difficulty seeing the benefit.
>
>   
>> Cool Cool Cool.
>>
>> Doing it in the style of the subversion book is going to be real cool.
>>
>> I am looking forward to contributing.
>>     
>
> Why is it more fun to contribute using Subversion than a wiki?
> _______________________________________________
> wp-docs mailing list
> wp-docs at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-docs
>