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(a)redhat.com>
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