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-inst...
- Karsten
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
On Tue, 2004-08-31 at 03:32, Mark Johnson wrote:
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?
Yes, sorry. docbook too has metadata, which isn't too regular (Due to be updated in 5.0 and regularised).
E.g. <article> <articleinfo> contains metadata.
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>.
I sort of gathered something along those lines was taking place :-)
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,
No way :-)
Having a contributors <section> (as part of the single, common file) would be a good way to handle long lists of contributors.
Docbook does allow for that in its markup. http://www.docbook.org/tdg/en/html/authorgroup.html
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>.
Customising it? +1 Probably not required for other than multiple author docs.
-
Dave Pawson -
Karsten Wade -
Mark Johnson