common opening sections (was Re: Style guide)

[Karsten Wade]

I think the below sounds reasonable and correct.  With this kind of
stuff, it's just so automatic for me to include it, and I haven't really
sat down to analyze a tutorial structure to break it out more clearly. 
I definitely think we need these common sections.

On Sat, 2004-08-28 at 19:33, Mark Johnson wrote: 

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

Since it sounds as if you are writing a set of these yourself, how about
if you complete your version and submit it as a draft for a common,
single <section> containing file.  That will be kept in
fedora-docs/common.  When we see your version in action, we can then
make any tweaks/suggestions, and then make it part of any document.

Few specific thoughts at this point:

> - 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
> - [....]???

That's pretty much it; just a sentence or two each, so this is about one
paragraph right at the start.


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

Agreed

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

>From Dave's response, I'm not sure I know what kind of metadata you are
talking about.  Is this part of the DocBook structure?

> 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

Having a contributors <section> (as part of the single, common file)
would be a good way to handle long lists of contributors.  Otherwise, I
would recommend hacking the stylesheet so we didn't have a full page of
authors as the standard DB stylesheets does for the <authorgroup>.

Another section we might consider is a document conventions section
[1].  Is this appropriate/necessary/useful for tutorial sized
documents?  It's probably also unnecessary for right now, but something
we could develop.  FWIW, I'm intere

[1] E.g.
http://www.redhat.com/docs/manuals/enterprise/RHEL-3-Manual/x8664-multi-install-guide/ch-intro.html#S1-INTRO-CONVENTIONS

- Karsten
-- 
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41