[standards-jig] Re: [docs] Doc feedback - things that should be fixed

Julian Missig julian at jabber.org
Mon Oct 15 20:22:04 UTC 2001


Replies within...

Iain Shigeoka wrote:

> At 05:56 PM 10/14/2001 +0200, you wrote:
> 
>> Some things I noticed in the docs, and that I think should be fixed. 
>> Overall, the docs are sadly not very coherent.. :/
> 
> 
> Agreed.  I've been suggesting changes through the standards-jig list as 
> part of the standards jig effort.  I forgot to Cc this list.  I wonder 
> which is the appropriate venue for it...  J.c/foundation guys have any 
> input?
> 
*SNIP*


Well, as far as I know, the standards-jig is not going to be involved in 
revamping the old docs. We don't like the old docs. They're a basis by 
which we can create new ones, but not things we'll be actively maintaining.

*SNIP*
> 
>> Finally, could somebody clarify what the current overall status of the 
>> docs is, and if anybody is working on something in this area? I see 
>> that (at least judging from docs.jabber.org) we still lack a single 
>> coherent description of at least the base jabber features (JPG is a 
>> good start, but it lacks to many things, and is more of a reference, 
>> with in many cases not enough explanation).
> 
> 
> This is my impression: Docs are in a bit of limbo as the foundation 
> settles down and standards are moved under the care of relevant jigs.  
> You should check out the new x:event revamp for what is being proposed 
> as the new doc format for standards.  I think that conversation went on 
> in standards-jig.  There are several people working on the problem but 
> from different angles and not in any really coordinated way right now.  
> My impression is that Peter Saint-Andre is probably the best person to 
> be called the coordinator of the docs effort (is this correct Peter)?

*SNIP*


Well, DJ Adams, Peter Saint-Andre, and I are at the head of the 
Standards-JIG effort to begin new documentation. As you mentioned, we 
are working on documenting Jabber piece-by-piece. We're starting with 
all of the currently implement namespaces, and we'll eventually get to 
jabber:client (the core of Jabber as it stands now). These documents can 
then all be linked together however people please, but our effort is to 
create the official documents for the Jabber protocol, not necessarily 
to create a convenient book for people to read through (although our 
documents should tie together fairly well).

My feeling is that we need to define what the standards actually are 
before we begin trying to describe them to people. By describing the 
standards in the fashion we did jabber:x:event, I feel we can do that.

Also, we're hoping that it will be easy to go from a JEP to our style of 
document after the JEP has been approved for a particular namespace.

We have a place to put our stuff in CVS, now we just need people to 
start volunteering to document the various namespaces in the fashion DJ 
Adams did.

Julian--
email: julian at jabber.org
jabber:julian at jabber.org




More information about the Standards mailing list