discuss: Thread: proposed outline: Author Guide

I'm looking over the contents of the Author Guide. The first thing I'd
like to recommend is a shuffling of the contents to reflect the process of
writing a submission for TLDP (the second would be deciding which
spelling of "catalog"/"catalogue" you're going to use -- is there a manual
of style that you use for co-authored documents such as this? 
e.g. Chicago Manual of Style?). 

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*. If the Author Guide were to talk about the writing process
and have a gentler introduction to mark up and then system configuration I
think this would help ease the anxiety around what actually needs to be
done to *write* the initial document.

Of course it is important to make the system configuration bits obvious so
that more experience authors can skip straight to those parts if need be.

I wrote out the outline on little slips of paper and then moved them
around until I felt they made a little more sense. This was a first crack
at it, so I'm sure there are things that can be improved on. My titles
might not be exactly right, but I have kept the numbers in so that you can
see where the content used to be. Square brackets indicate the approximate
content of the page currently. I believe I've kept all of the original
content, if I've omitted a section it was not intentional.

It seems as though the Author Guide is now recommending the use of XML. I
would make that a consistent recommendation throughout the guide and
remove the references to SGML/XML differences. Or perhaps put them in the
back as an Appendix. The newbie authors like myself are not likely to need
a break down comparing SGML and XML, in fact it only serves to confuse me
on what I'm *actually* supposed to be doing. I doubt there are many
oldtimerSGML geeks out there who haven't figured out what XML is all
about. There are more likely to be people like myself who are coming from
HTML, not SGML.

Note that I've moved System Setup to the *end* of the markup section. As
someone who is totally comfortable with editing HTML by hand I don't
actually NEED to set up my system to deal with DocBook, I just need to
write it in a plain text editor. If I want to validate my document then I
need to set up some tools, but it should not be considered a pre-requisite
in my opinion.

Let me know what you think. :)
emma

ABOUT THE GUIDE
	Purpose/Scope of the Guide (1.1)
	Feedback [email Mark] (1.3)
	Copyrights and Trademarks (1.4)
	Acknowledgments and Thanks (1.5)
	Document Conventions [visual output of various things e.g. warnings] (1.6)

THE LINUX DOCUMENTATION PROJECT
	About the LDP (1.2)
	The LDP (2.1)
	Why use DocBook instead of other formats (2.3)
	I want to help (section of FAQ, #9)
	About the process (NEW)

GET INVOLVED	
	For new authors [general process; resources for author] (2.5)
	Mailing lists (2.6)

PROPOSE
	Deciding on a subject (5.1)
	Finding a document that is not maintained; contact the author (etc)
		(NEW)

WRITING
	Developing an outline (5.2)
	Writing the text (5.3)
	LDP Style Guide HOWTO [URLs for sources of technical writing] (5.6)
	Editing Tools (NEW: gentle intro glean from 3.5)
	Editing and Proofing the text (5.4)
	CVS (NEW: general intro pointing to CVS Part #2)
	Other tools/reference [ispell, aspell, docbook definitive guide] (3.7)
	Taking over an unmaintained doc/editing an existing doc (NEW?)

MARKUP
	DocBook [about SGML] (2.2)
	Intro to DocBook (4.1)
	DocBook versions [accepted versions by the LDP] (6.5)
	Don't know SGML/Don't like (pulled from the FAQ #9)
	Catalog files gentle intro (NEW -- parts taken from 4.3)
	DocBook DTD [where to get DTDs] (3.2)

	EDITORS
	Editing Tools (reminder from WRITING and point to configuration
	information in VALID DOCUMENTS AND SYSTEM SETUP)
	
	ELEMENTS AND ATTRIBUTES (THE MARKUP)
	Writing in DocBook XML [difference between SGML/XML; DocBook 3->4]
		(2.4)
	Writing DocBook Elements [chart of useful markup] (4.4)
	Obsolete tags (6.6)
	
		ADVANCED MARKUP
		Images (7.1, 4.6 and 6.4)
		Indexes (4.5)
		Tables (4.7)
		Listings and Program Codes (4.8)
	
	CONVENTIONS
	Conventions (6.8)
	Tag minimization (6.7)
	Naming separate HTML files (content perspective) (7.2)
	
	VALID DOCUMENTS AND SYSTEM SETUP
	Configuration needed [exporting SGML_CATALOG_FILES] (4.2)
	Editing Tools [configuration] (3.5)
		
		ADVANCED SETUP
		Creating and modifying catalogs (4.3)
	
TEMPLATES AND DOCUMENT COMPONENTS	
	Revision history (6.2)
	Date formats (6.1)
	License (glean from 8.2)
	Abstract
	Sample Article (6.3)
	Document Samples (4.11)

DISTRIBUTION AND PUBLISHING
	Before you distribute [spell check; review; validate; create web site
		for original doc] (8.1)
	Copyright and Licensing Issues (8.2)
	Submission to the LDP [email or email + CVS]
	Can I publish documents in the LDP? (Pull from FAQ #9)

TRANSFORMATIONS (MAKING HTML OUT OF XML)
	Crediting translators and converters (4.9)
	Tools and Hints (4.10)
		includes: compiling sources, inserting summary on initial article
		page, inserting indexes, marking notes on text, reusing parts of
		the document
	DSSSL (3.1)
	Jade (3.3)
	Jade Wrappers (3.4)
	Naming separate HTML files (transformation HOWTO) (7.2)
	Using the LDP XSL style sheets (7.4)
	Using ldp.dsl (7.3)

MAINTENANCE
	Maintaining your HOWTO (5.5)
	Maintaining your HOWTO (8.4)
	Content errors (was in FAQ #9)
	CVS [maintaining documents; repository notes; recovering old versions
		etc] (3.6)

-- 
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]

On Tue, Jul 08, 2003, Emma Jane Hogbin wrote:
> I'm looking over the contents of the Author Guide. The first thing I'd
> like to recommend is a shuffling of the contents to reflect the
> process of writing a submission for TLDP (the second would be deciding
> which spelling of "catalog"/"catalogue" you're going to use -- is
> there a manual of style that you use for co-authored documents such as
> this?  e.g. Chicago Manual of Style?). 

My very loose memory is that you just need to choose a consistent style
-- the editors guide specifically requests that as long as the spelling
is consistently British or American, that the editor not change it.

-Mary

On Mon, 2003-07-07 at 22:15, Mary Gardiner wrote:
> On Tue, Jul 08, 2003, Emma Jane Hogbin wrote:
> > I'm looking over the contents of the Author Guide. The first thing I'd
> > like to recommend is a shuffling of the contents to reflect the
> > process of writing a submission for TLDP (the second would be deciding
> > which spelling of "catalog"/"catalogue" you're going to use -- is
> > there a manual of style that you use for co-authored documents such as
> > this?  e.g. Chicago Manual of Style?). 
> 
> My very loose memory is that you just need to choose a consistent style
> -- the editors guide specifically requests that as long as the spelling
> is consistently British or American, that the editor not change it.

Agreed.  I think that went for Australian conventions as well.  Also,
when I work on documents written by authors whose second language is
English, I'll try and keep consistent with the style used, so long as it
is grammatically correct, and done throughout.  

There was a list set up last year for collaboration on an LDP Style
Guide, but there hasn't been activity for some time.  Aside from the
variations on English style, I don't know if there were any other style
issues to address, so more discussion on that may be a good idea, and if
it fits, some information could be included in the Author Guide.

--
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)

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

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.
> 
> 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).
 
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.

> 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.

> 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.

Unfortunately, that's a college degree in itself (technical
communication).  It's a large field.

-Mark