[JDEV] Jabber Documentation

[Adam Theo]

I've been in a serious Jabber documentation mood lately, and instead of 
letting it go to waste, I've decided to revamp the Jabber documentation. 
  I'd like to try and revamp all of it, but first I need a plan. I feel 
there needs to be a great restructuring first.

Here are some docs I've been developing with help from the Jabber 
community: Jabber Education Document (a concise introduction to Jabber) 
[http://www.theoretic.com/?Jabber_Education_Document] and the Jabber 
Client Guidelines (suggestions for client design) 
[http://www.theoretic.com/?Jabber_Client_Guidelines]. I could see alot 
of this information going into the FAQ, Technical Overview, and Client 
Developers Cheat Sheet. I also have plans for a "Complete History of 
Jabber" document and improvements on the Glossary.

Also, the Jabber User's Guide seriously needs an index/table of 
contents. Forcing readers to take it step by step isn't very friendly.

Here are my thoughts on how documentation for jabber.org should be 
restructured:

The FAQ would be a list of short questions and answers as it is now, but 
would also be a quick-scan document to quickly find references to the 
other docs. It would pull the other documents together in one place, 
linking off to them under relevant topics for details. Much of my Jabber 
Education Document would go in the FAQ, with links off to the other docs 
for details.

I would create a ""Complete History of Jabber" doc which is one such 
detailed doc which would be linked to from the FAQ.

The Jabber User's Guide has great content, but needs an index for easy 
navigation.

Rename the Client Developer's Cheat Sheet to "Jabber Client Developer's 
Guide" (JClDG) to fall in line with the other guides. I'd add alot more 
info there and this is where alot of my current "Jabber Client 
Guidelines" work would go.

Rename the "Introduction to Components" to the "Jabber Component 
Developer's Guide", adding alot more info. However, one question is 
whether how jabberd-centric components are? After all, a jabberd-centric 
document should go on the jabberd website, not the jabber.org one. I 
take it the rules for creating components are different between the 
JOSS, JCS, TIMP, Merlin, and other servers which are popping up now...

Finally, I think all documents on Jabber.org should be in the same 
location on jabber.org, instead of being spread out among different 
websites and directories. I'd like to revive the docs.jabber.org 
subdomain, using that instead of www.jabber.org/docs/ . Under that would 
go directories for each of the guides (JUG, JPG, JClDG, JSDG, JCpDG, 
etc...). We don't need the html part in the URL. The text (and other 
format) versions can be in the directory along with the html versions. 
I'd also reccomend having the docbook version in the same directoru for 
easy downloading.

Now, the docs.jabber.org site can (and should) link to other sites, 
especially the jabberd.jabber.org site (and the jabberd howto), links to 
the growing number of books on jabber, and links to other 
documentation/information websites as now (although I'd like theoretic 
added to that list, *grin*).

And yes, I'm prepared to do all this work, I just want approval to go 
ahead and do it. Better say "yes" fast, though, before my documentation 
craze runs out  :-)

-- 
     /\  Adam Theo, Age 22, Tallahassee FL USA
    //\\   Email & Jabber: theo at theoretic.com
   //  \\  (Boycotting AOL, therefore no AIM or ICQ)
=//====\\=  Theoretic Solutions: http://www.theoretic.com
//  ||  \\     "Bringing Ideas Together"
     ||      Jabber Protocol: http://www.jabber.org
     ||         "The Coolest IM on the Planet"
     ||  "A Free-Market Socialist Patriotic American
     ||      Buddhist Political Philosopher."