Style guide

[Dave Pawson]

On Sun, 2004-08-29 at 03:33, Mark Johnson wrote:

> 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)?

Suggest minimally a *info for the top level, perhaps one per
separate file (delivered) which would be sect1.
 This to allow some record of changes with the actual document.

For any more, perhaps a better question is who want the metadata,
hence what might they want?
  And I can't think of any 'customers' for metadata.


> 
> 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.

Yes, but only a few lines/couple of para's; intention to stop people
who are reading the wrong doc?


> 
> - scope of this document (what it does/doesn't addressed in this
>    section.

Ditto above?




> 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.

Our definitions of metadata are at different levels :-)
Audience, goals etc I'd see as part of the document.
No matter.


-- 
Regards DaveP.
XSLT&Docbook  FAQ
http://www.dpawson.co.uk/xsl