[wp-docs] DocBook, anyone?

[Cena Mayo]

Ryan J. Markel wrote:

>   Maybe I'll start working towards being the long-term DocBook 
> author.  :)


Just a note:  it's important (I think) that there is never just one 
person capable of doing a given job.  Imagine how easily things could 
come to a screeching halt if that were the case.  When I think of the 
Docs team in the long term, I envision not only user and developer docs, 
but also docs specific-ish to the docs team that new (or old members) 
can be referred to.  A tutorial on using DocBook might be just such a 
text, if someone wrote such a thing. *gazes at the moon* :)

> So then, what about short-term solutions?  How do we go about 
> formatting the documentation and collating it all into a single area?

In the past, Craig developed a 'WP Tutorial' style sheet that can be 
seen <a 
href="http://blog.nuclearmoose.com/wp-docs/wp-layout-explained.htm">here</a>.  
I believe there were some issues with it and that Craig has been working 
on developing a new one. (Right, Craig? :))  In the meantime, there's 
certainly nothing to stop you from writing a doc using Notepad; the 
important thing is to start writing.  As Craig mentioned in a previous 
email, send finished works to him (or me) for editing; they eventually 
will be posted to the list for peer review before final release.  The 
end goal is to have these works hosted on the wp.org site, nicely 
formatted and all.

> Do we operate with shorter tutorials on singular subjects, with a 
> master linking page manually organized by topic, or do we try to 
> collaboratively work on a larger documentation set that would be a 
> large, expansive document?

In the past, we've mostly written shorter tutorials on a wide variety of 
subjects, but I see the main goal as providing a more comprehensive 
user's manual, starting with 1.2 (do you have an ETA on release, 
Matt?).   I think that the way the docs page (on wp.org) is organized 
allows for short tutorials linked by topic, but again, I personally 
believe that we should be working on a larger set, as you mention.  
Toward that end, I've been working on an rough outline for said doc that 
I'll try to post by Sunday.

>   Getting at least marginal official documentation out there would be 
> a great start, even if it is in small bits and pieces for the time being.


I wholeheartedly agree.

Cena