discuss: proposed outline: Author Guide
Subject:
Re: proposed outline: Author Guide
From:
Glen Turner ####@####.####
Date:
8 Jul 2003 06:27:21 -0000
Message-Id: <3F0A6445.8070506@aarnet.edu.au>
Emma Jane Hogbin wrote:
> My feeling is that the document is very
> overwhelming to new writers because it gets almost immediately into the
> configuration of many things which are NOT required to prepare a document
> for the LDP. For example: it is not actually required to markup a document
> in DocBook format according to the Author Guide. It's nice, yes, but not a
> *requirement*.
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.
What would be really nice list a huge section listing
all the markup templates
- program listing extract
- screen shot
- prompt, command, input, output
- boot title
- program name
- command name
- a cross reference
etc, etc
as this would remove a lot of the mystery out of DocBook.
A lot of the current examples are broken (put a < into
the code of the listing exmaple).
It's still not clear to me how to get a DIA diagram into
an LDP document.
I agree that it's worthwhile discarding all the SGML stuff.
DocBook/XML is what is supported out-of-the-box for most
recent Linux distros and the "xmlto" command simplifies the
document production process no end.
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.
Computer documentation does differ from writing which people
are taught at school and it's these differences which the LDP
author guide should draw out.
I like that the current guide gives people a heads-up about
maintenance issues (CVS, maintainance). To this list could
probably be getting a e-mail account just for the HOWTO.
--
Glen Turner Tel: (08) 8303 3936 or +61 8 8303 3936
Network Engineer Email: ####@####.####
Australian Academic & Research Network www.aarnet.edu.au
--
linux.conf.au 2004, Adelaide lca2004.linux.org.au
Main conference 14-17 January 2004 Miniconfs from 12 Jan
