R: [Foundation] Jabber Documentation

Marco Palombi marco.palombi at tipic.com
Sat Jun 15 01:51:30 CDT 2002


Theo,

did you have a hear in Munich :-)

We have been going through the same at the Foundation meeeting there
yesterday. It is good that we feel the same need.

Peter took some notes during the meeting that can be integrated with your
notes here.

-marco

Marco Palombi
Tipic
blog: www.tipic.com/blog/ocrampal at tipic.com
email&jabber: ocrampal at tipic.com



> -----Messaggio originale-----
> Da: members-admin at jabber.org [mailto:members-admin at jabber.org]Per conto
> di Adam Theo
> Inviato: sabato 15 giugno 2002 2.18
> A: jdev at jabber.org; members at jabber.org
> Oggetto: [Foundation] Jabber Documentation
>
>
> 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."
>
> _______________________________________________
> Members mailing list
> Members at jabber.org
> http://mailman.jabber.org/listinfo/members




More information about the Members mailing list