common opening sections (was Re: Style guide)

[Mark Johnson]

Karsten Wade wrote:
> 
> 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.

Sounds like a reasonable plan.

I'll also take a look at a bunch of my favorite O'Reilly books & 
pocket references to see that they have for these types of sections 
in their intro sections/chapters.

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

I confess to using the term metadata a bit loosely.

The above statement simply asks which of the above suggested 
subsections would make sense to include in the introductory 
<section>. The subsections do, indeed, provide document metadata 
(=data about the document), but if someone wants to start a semantic 
argument about the meaning of metadata, I'll forfeit and stay out of 
it. More pressing matters await:)


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

This is definitely a policy issue, the chief ramification being that 
with <authorgroup> you don't get to thank ^X\@/farb34 for searching 
for foobar archives for valuable data. You just can't do any sort of 
natural, narrative-like acknowledgements in the authorgroup construct.

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

IMO, not needed at this point, but easily added later as an external 
entity to the introductory secion.

Cheers,
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