Re: author's guide

[Deb Richardson <deb@thepuffingroup.com>]

Gary Lawrence Murphy wrote:

> I realize you've only just started, but so far, I don't really get any
> sense of the OSWG book being any different in scope from Norm's book

Actually, it's quite different in that it is to be a task-based approach
to learning/using DocBook, rather than a reference-guide for the DTD and
its elements/entities.  

> Such a book needs to focus on cookbook examples, of using DocBook to
> solve a wide array of real-world problems. The structure of the book
> should be driven by those real-world examples rather than on the
> components and structure of DocBook itself.

That's pretty much what the Practical Guide aims at doing -- perhaps
that doesn't come out in the outline in its current draft.

> This is not a criticism,
> but if I was doing such a book, this is the approach I would take.

That's really the approach I intend to take -- rather than being an
alphabetical list of elements, it is organized according to the markup
task the author is trying to accomplish.  The "cookbook"-style sections
are the step-by-step examples.  
 
> The OSWG DocBook outline starts with this approach.  There are
> sections on 3 generic document types, but I wonder if there may be
> different scenarios for each type of document. For example, is an
> article an article, or are some of them a conference paper? How do I
> manage a submitted chapter on a large book, a news article, a web-news
> article ...

Trying to cover all the possible permutations means that the book
approaches the infinite.  It can be cooked down to a much simpler level,
however, while still being useful.  An article is something that doesn't
have more than one chapter, a book is something that has more than one
chapter, a ref page is a short and very specific type of document.  How
these are used is up to the author.  I have seen books that (imho) would
be better done as articles, and articles (again, imho) that would be
better done as books.  Discussion on the specifics is something better
left, I think, to the individual documentation projects -- which puts it
outside the scope of the OSWG's Practical Guide.  

What the FreeBSD project decides is an article, for example, might be
completely different than what the LDP decides is an article.  A HOWTO
could be either a book or an article, depending on the length and scope
of that HOWTO.  Etcetera.  

I do intend that there be lots of examples in the Practical Guide --
thus the "examples" appendices.  Also, the whole book should be peppered
with examples of varying lengths.  "Show, don't tell" applies
particularly well to technical documentation, after all.
 
> Also, I'd begin with a simple reference page, then move up to an
> article and end off with a whole book rather than the other way
> around.  

Reference pages are far too specific to be useful as a learning tool.  I
might switch the "article" and "book" sections around, but the Practical
Guide isn't really intended to be read in a linear fashion -- the TOC is
supposed to be verbose enough that folks can dive in where they need, to
the information they're looking for as quickly as possible.  Each
section will be largely self-sustaining, and whether "book" or "article"
comes first is largely irrelevant.

Style guides should be separate from basic DocBook tutorial information,
imho.  What authors learn about DocBook should be independent from the
project they are working on.  

> The section on processing tools may be a winding garden path.

I'm really not quite sure I understand this.  There are a limited number
of tools available, and none of them are particularly difficult to learn
how to use.  DocBook Tools, Jade, sgml-tools, etc.  As new tools are
created, they get a section in the book.  

> Rendering documents is easily a completely new book (or so it seems to
> me right now ... I talk to DSSSL vs XSL people and they might as well
> be speaking Greek) --- for the purposes of this doc, you may want to
> follow Norm's lead and only tell them how to process the most basic
> presentations, then start a parallel book on the various flavours of
> stylesheet engines (or whatever they are called).  If content and
> presentation are truly seperated, these are different audiences
> anyway.

You're abstracting this a little too far.  Bob the HOWTO writer doesn't
care about dsssl engines and processing tools...he wants to be able to
validate his doc, get some basic output, and know that what he's done is
basically correct.  People who want to learn about the complex stuff
have other resources for learning it.  Bob wants to be able to type
"db2html" on the command line and turn his DocBook instance into HTML. 
When he submits that into the OSWG CVS, the output is going to look
different because we use a different CSS.  The important thing is that
he can turn it into basic HTML, and he can debug his own markup.  

That's really not a book in itself...it's a series of short
"installation and use" sections for the various tools that are
available.  
 
> They just can't let go of content, and writers can't let go of
> presentation ... old habits die hard.

There is a fuzzy line between structure and formatting, of course, but
the basics ("italics" is formatting, "filename" is structure) isn't
really rocket science.  Yes, it's difficult to get rid of all the
habits, but the basics are pretty simple.  Not having a "WYSIWYG" editor
for doing DocBook is a good thing in this context.  
 
> Authoring tools may be a really short section if you are only talking
> about free editors ... basically, there is only one practical
> solution: Emacs/psgml.

Oh, pshaw.  I use vi for all my markup, and have done so for years. 
There's also LyX, which I know supports at least DocBook articles
already, and has supported LinuxDoc for ages, etc.  I don't use emacs,
and have no intention of doing so :>   No, there is no magical "markup
mode" for vi -- I do, in fact, type all those tags by hand.  You really
get used to it after a while, and it's easier if you remap . to < and ,
to < (it's just a flip remapping).

And we don't necessarily have to talk just about free editors.  If
someone wants to write a section on a non-free editor, they're more than
welcome to do so and submit it.  The Practical Introduction outline is
not a concrete thing, and there is no real "end point" -- it's meant to
be a document that grows and evolves over time.  Like free software,
free docs have a flexibility that closed docs do not.  New editions of
the book will be generated daily -- the version number will just
increment when need be.

- deb 


-- 
deb@thepuffingroup.com
deb@linuxchix.org
deb@oswg.org


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