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 aretalking 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@xxxxxxxxxx> 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
