common opening sections (was Re: Style guide)
mjohnson at redhat.com
Tue Aug 31 02:32:33 UTC 2004
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.
>>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
> 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
> . 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.
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
More information about the docs