discuss: proposed outline: Author Guide
Subject:
Re: proposed outline: Author Guide
From:
Emma Jane Hogbin ####@####.####
Date:
8 Jul 2003 14:56:44 -0000
Message-Id: <20030708145643.GA578@xtrinsic.com>
On Tue, Jul 08, 2003 at 09:50:36AM -0400, Mark Komarinski wrote:
> On Tue, Jul 08, 2003 at 03:57:17PM +0930, Glen Turner wrote:
> > As someone's who has written a HOWTO, I found that the DocBook
> > stuff was too thin on examples. Program listings, etc aren't
> > "advanced markup" but are at the heart of the "explain, describe,
> > show" approach taken by most LDP authors.
I would say they are a more advanced concept as there is not a close match
in HTML, a language I'm assuming most authors will be familiar with.
Mostly I picked "advanced" topics based on how clear the actual page was.
Program listings looks like a complicated page when you blink at it. If
you warn the reader that they're going to have to think about the page
before they read it then I think they'll find it a lot easier to swallow.
My intention was to not change any of the content in the first shuffle.
> > What would be really nice list a huge section listing
> > all the markup templates
I have mixed feelings on this. I think if there were an LDP style guide
that says "this is how we recommend you make a ***" then it would be useful.
If it's just going to be a huge table without descriptions and context I
don't think it's any more or less useful than what DocBook has already
done themselves.
I think it would be useful is to look at document components and
explain them. For the "code" bits I would give rationale on why it's used
this way. For the "before" stuff I would simply give a "this is how we do
it" explanation. As an author I could also then use it as a checklist to
make sure I had all of the correct bits (Tabatha had to re-write most of
my "before" content because it wasn't in the right format, although it
validated as DocBook).
e.g. (much of this is already in the table listing)
before: author info, dates, versions, copyright etc
content: lists, paragraphs, sections, application
asides: warning, note, tip
commands: userinput, parameter, option
display: screen
references: sample of how to make a bibliography, link within a
document
after: license, appendix
> A lot of this has already been done. Either by purchasing DocBook: TDG,
> or by looking at it online (http://www.docbook.org/tdg/en/). When I wrote
> the LAG, I didn't want to duplicate a lot of effort, mostly because
> I'm lazy.
Forget about the lazy factor! The DocBook web site is really easy to use!
The elements are cross-referenced and tell you what other things you
should consider that are similar; it tells you what an element must
contain; and what it may be contained in; and it tells you the attributes
you can use. What the DocBook is lacking is good descriptions of when to
use the elements--it's a little too flexible perhaps.
> > I can't see the point of the LDP Author Guide repeating the
> > stuff which appears in hundreds of "How to write" textbooks.
> > So I can't see why you'd want anything but the most basic
> > description on developing a guideline, etc.
>
> The idea of this was more of a style guide, so all documentation
> has the same look-and-feel in terms of flow.
I think it's nice to have the "How to write" sections. They don't need to
be the longest part of the document, but they are part of the process. I
think the document is a process document, just not in the right order yet.
When you've spent ages muddling around in the content you don't always
remember to spell check. It's obvious to most that you should, but that's
where a process document is nice--it lets you evaluate where have I been
and where do I go next.
emma
--
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]
