Style guide

[Mark Johnson]

Hi All,

(Probably should've started a new thread for this...)

As I'm working on the Emacs/DocBook Quickstart guide, it occurs to 
me that that perhaps we should provide some required sections in the 
beginning of the document that would be intended to address such 
questions as (realizing that the following are not logically 
independent):

- intended audience
- scope of this document
- what this document addresses
- what this docuemt does not address
- goals of this document (a pseudo re-phrasing of the above)
- contributors to this document
- scope of this document
- [....]???

My feeling is that context that the above info provide are very 
important, in that they allow the reader to quickly assess the scope 
of the document and, hence, whether it is worth their time to read 
it.  Past experience has shown that the mandatory inclusion of this 
sort of info a document/tutorial provides valuable info to the reader.

My points (and questions), are then:

- What, if any, should be the required metadata content for standard
   fedora docs (which at this point are tutorially structured)?

Put another way, should we require some initial sections titled, e.g.:

- intended audience

- goals of this document (N.B. these are different from the scope as
   described below), and also provide a basis from which readers can
   file bug erports. E.g. Bug pointing out how doc doesn't achieve a
   given goal.

- scope of this document (what it does/doesn't addressed in this
   section.

- contributors

'Just thinking out loud here, but honestly do feel strongly that 
providing a template that requires some of the above-mentioned 
sections would add much value to docs generated by the fedora docs 
project.

Since this is a rather high-level policy decision, I'm hoping to get 
feedback on this ASAP, as this sort of policy content would affect 
all docs written for fedora.

FWIW, I'm also a Debian (www.debian.org) developer and have found 
that clear (& existing) policies regarding the requirement of 
content of the type I'm advocating is greatly helpful to both 
authors & readers. In short, it works.

Please post your comments relating to my suggestion/proposal to the 
fediora-docs list. I'm interested in hearing what others think about 
my ideas to require initial content of this sort.

FWIW, the inclusion of this type of document metadata is used by a 
number of orgnaizations, so I'm not proposing anthing new here. 
Standard stuff, but can add great value to a document.

Thanks,
Mark

-- 
----------------------------------------------------------
Mark Johnson                     <mjohnson at redhat.com>
OS Product Documentation Group
Engineering, Red Hat, Inc.       <http://www.redhat.com>
Tel: 919.754.4151                Fax: 919.754.3708
GPG fp: DBEA FA3C C46A 70B5 F120  568B 89D5 4F61 C07D E242