[standards-jig] Re: [docs] Doc feedback - things that should be fixed
julian at jabber.org
Mon Oct 15 20:22:04 UTC 2001
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
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.
>> 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)?
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
email: julian at jabber.org
jabber:julian at jabber.org
More information about the Standards