Hi All,
(Probably should've started a new thread for this...)
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):
- 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 - [....]???
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)?
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
'Just thinking out loud here, but honestly do feel strongly that providing a template that requires some of the above-mentioned sections would add much value to docs generated by the fedora docs project.
Since this is a rather high-level policy decision, I'm hoping to get feedback on this ASAP, as this sort of policy content would affect all docs written for fedora.
FWIW, I'm also a Debian (www.debian.org) developer and have found that clear (& existing) policies regarding the requirement of content of the type I'm advocating is greatly helpful to both authors & readers. In short, it works.
Please post your comments relating to my suggestion/proposal to the fediora-docs list. I'm interested in hearing what others think about my ideas to require initial content of this sort.
FWIW, the inclusion of this type of document metadata is used by a number of orgnaizations, so I'm not proposing anthing new here. Standard stuff, but can add great value to a document.
Thanks, 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
