Re: Outline for Author's Guide

[Kendall Clark <kclark@ntlug.org>]

>>>>> "Gary" == Gary Lawrence Murphy <garym@canada.com> writes:

    Gary> Agreed the relative dearth of features in the old linuxdoc
    Gary> will not make for a complete DocBook, but we don't want to
    Gary> overwhelm anyone.  Adding a bunch of sample widgets because
    Gary> we think they may be needed may just confuse people.

No one is suggesting we do that. What I think we're suggesting is that
since moving to DB presents an opportunity to take advantage of SGML
features there needs to be some guidance as to how these features are
used.

    Gary> We can start with the stripped down linuxdoc conversions,
    Gary> then perhaps add some widgets to them --- if people like
    Gary> them, we have just upgraded an old doc, and if people don't
    Gary> like them, we don't have two dozen authors all working in
    Gary> parallel putting these widgets into every new document.

I don't know what 'widgets' means in this context, sorry.

    Gary> I'll stick to my guns: Even Norm Walsh's DocBook guide shows
    Gary> that even he has very little experience in how such
    Gary> documents are actually used: The review people at MCP have
    Gary> already been responsible for many changes and additions to
    Gary> his online book, all done in the name of wide-audience
    Gary> useability.  If Norm can't get it right flying blind, do we
    Gary> really have a chance?  I'm only suggesting we walk before we
    Gary> run, and maybe even crawl first.

This doesn't mean anything; as I said before, most of the stuff in the
AG is SGML usage stuff, not presentational. The AG isn't meant to
serve as an information design manifesto; rather, it's meant to lay
down a standard that LDP authors can follow so they can know *how* to
use SGML properly, that is, consistently across a collection.

On the vast majority of these issues, I daresay most LDP authors won't 
care one way or the other what the standard is.

Gary, have you actually looked at the outline I proposed? I'd sure
like to hear what things specifically seem to you to be the kind of
thing we should discover in the way you suggest.

I'm now not sure what your point is, I'm afraid: are you doubting the
need for a Style/Author's Guide at all? Or just that we're proposing
going about creating it in a way you don't agree with?

I think Ed Bailey's point about needing an Author's Guide for the Red
Hat docs is a good one.

    Gary> By working with the linuxdocs, we can see what exactly is
    Gary> missing, do some experiments to add them in (by hand if
    Gary> necessary) and from the user feedback, we can formulate
    Gary> policies; once we have enough policies to make for a
    Gary> complete document, we can then announce that all future docs
    Gary> will be LDP-DocBook DTD and distribute the DTD, our
    Gary> stylesheets and our Author Guide.

Sorry, but I can't follow this; it's rather vague. What is the 'them'
that we might add in, perhaps by hand?

Example: what kind of user feedback do you suspect we'd get from LDP
authors with regard to, say, entity engineering? I daresay most LDP
authors don't know what entities are, much less how they can be
used. This isn't a value judgment about them, just a fact about their
experience, or lack thereof.

Example: what about naming conventions? We need them, don't have them, 
but as they are almost *purely* conventional, it hardly matters what
they are as much as *that* they are. I don't think LDP author feedback 
will help or hurt the adoption of naming conventions; but it certainly 
will delay their adoption.

I think many of the AG issues are just like that: they are a matter of 
convention and, as such, *can* be decided by a committee. At least,
that's my analysis of the situation.

You said earlier that this committee didn't have sufficient experience 
to pull off an AG; maybe you're right, though I doubt it. But the LDP
authors as a group have vastly less DB/SGML experience. I think that's 
the basic consensus. 

I guess this is why there is chocolate *and* vanilla. I don't agree
with your approach, but if it's the one that is implemented, I'll play
nice. :>

<Kendall/>


--  
To UNSUBSCRIBE, email to ldp-docbook-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org