cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Linden H van der (MI)" <H.vanderLin...@MI.unimaas.nl>
Subject [Daisy/Docs] Styling conventions
Date Fri, 10 Jun 2005 08:28:19 GMT
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: 

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

- 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

Mime
View raw message