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-i...
- Karsten
--
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41