Re: Outline for Author's Guide

["Edward C. Bailey" <ed@redhat.com>]

(I'll preface my comments by saying I've not seen the AG outline, so
hopefully I won't be speaking at odds with that document, but here
goes... :-)

>>>>> "Kendall" == Kendall Clark <kclark@ntlug.org> writes:

Kendall> I've done enough DocBook with teams of 10 to 20
Kendall> authors/editors/content-personnel to know that a "quick FAQ" will
Kendall> not suffice.

I'd have to agree.  One of the problems I had with our LaTex > DocBook
conversion was that I didn't have a "best practices" document that I could
point my staff to, and say, "make your documents adhere to these
guidelines."  I was never more than a week or two ahead of them in terms of
my knowledge of DocBook, and I quite often found myself having to correct
their work because they just didn't have a standard to work from.

If nothing else, the AG should give the authors some idea of the way to
handle the more common markup situations, define commonly-used entities,
etc.  A quick review of the available tools would be handy, too (although I
imagine that as time goes on, this will be less of an issue, as more
distributions will ship reasonable DocBook-friendly tool configurations).

...
Kendall> This is important so that authors will know which precise DB
Kendall> constructions they want to use *from among a range of options* to
Kendall> get the desired effect. Yes, separating content from presentation
Kendall> is essential to an SGML project; but individual authors are still
Kendall> going to be asking questions like, 'how do I get this bold or
Kendall> italic?'. Even if we want to help them think about their documents
Kendall> in more semantic, and less presentational terms, we still have to
Kendall> handle the transition cases.

Yes, and from what I've seen of linuxdoc, it appeared to be heavily biased
towards presentation, which will lead to more author confusion/frustration,
as DocBook is just as heavily biased towards semantics.  We used LaTeX
command definitions that gave reasonably semantic markup (which make our
conversion to DocBook a bit easier), but even so, my staff was still doing
ugly things like marking up a sample grep command using <filename> "because
then it'll come out in Courier".  Old habits die hard, but to really
benefit from SGML's separation of semantics and presentation, you really
have to make that break completely.  I predict this will be an area that
will require significant effort in order to get the authors on the DocBook
bandwagon...

                                Ed
-- 
Ed Bailey        Red Hat, Inc.          http://www.redhat.com/


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