discuss: proposed outline: Author Guide
Subject:
proposed outline: Author Guide
From:
Emma Jane Hogbin ####@####.####
Date:
8 Jul 2003 04:29:25 -0000
Message-Id: <20030708042924.GD935@xtrinsic.com>
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 ]]
