), subsections with 'Heading 2' (

Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Received-SPF: pass (hermes.apache.org: local policy)
Content-class: urn:content-classes:message
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Subject: [Daisy/Docs] Styling conventions
Date: Fri, 10 Jun 2005 10:28:19 +0200
Message-ID: <329A68716B57D54E8D39FD3F8A4A84DF0282ADD3@um-mail0136.unimaas.nl>
Thread-Topic: [Daisy/Docs] Styling conventions
Thread-Index: AcVtllwmnXz5NScBSaqiZtf6tLLSBw==
From: "Linden H van der (MI)" <H.vanderLinden@MI.unimaas.nl>
To: <dev@cocoon.apache.org>

To all document editors,

Seeing Mark's work and my own I decided that we best set some basic
rules for writing the documentation and using particular styling. This
improves a consistent look and prevents tedious cleanup at a later
stage.

This is what I propose (and I know _I_ haven't been consistent):

- when describing what to do, mark the text that is shown on screen with
italics. Example:

Choose <i>Menu</i> > <i>Option</i>
Select the tab <i>SomeTab</i>

- when describing what to enter, put the text in a separate 'Formatted'
(<pre>) paragraph. Example:

Now enter:=20

<pre>Some command here</pre>

If possible rewrite the sentence to something like "instructions": "text
to enter", unless that becomes very awkward. In that case put the text
to be entered in bold or italics (let's decide which one).

- I prefer to mark environment variables and similar things with bold,
although I haven't yet decided where to draw the line. Text should be
readable, not colorful. ;-)

- remove any <p> tags within a <li> list item</li>=20

- for now: let's start marking section headers with 'Heading 1' (<h1>),
subsections with 'Heading 2' (<h2>) and so on, irrelevant of the
importance of the section compared to other documents. I know I started
with <h2> sometimes.

Note: I assume that setting this styling is done through the HTMLarea
editor, not directly in the textarea editor.

WDYT?

Bye, Helma