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-install-guide/ch-intro.html#S1-INTRO-CONVENTIONS - 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
