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
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(a)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