I started this a while ago and some of this has been brought up by
Ross so some is a repeat. The most important thing is that we be
consistent in style. It will make users lives much easier if we have
a single set of conventions.
On Jun 10, 2005, at 3:28 AM, Linden H van der (MI) wrote:
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 essential in the finished product. Tedious cleanup is to be
avoided. While I know its not possible now, we need to take advantage
of Cocoon's transformation abilities. Right now I am concentrating on
content. In the future I think it would be wise to come up with a set
of tags for the documentation such as
<instructions>
<step>...</step>
</instructions>,
<code>...</code>
etc.
This would separate the content from the presentation, making the
documentation process about documentation. In the future we would
just need to change the xsl or css to change the presentation.
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>
I prefer bold, but I speak italics as well. ;-)
- when describing what to enter, put the text in a separate
'Formatted'
(<pre>) paragraph. Example:
Now enter:
<pre>Some command here</pre>
see above. While this is necessary right now, it will present
problems keeping things consistent. One of the many problems that are
encountered is the number of spaces to indent the instructions, or
wether they should be indented at all.
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 would change the font. Use <code>.
- 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.
Another use case for using tags. I've had this problem on several
sites. We wound up using just <h> tags that were transformed to the
appropriate xhtml tag based on wether they were contained with in a
page, section or subsection tag.
Note: I assume that setting this styling is done through the HTMLarea
editor, not directly in the textarea editor.
WDYT?
This is the only way to go at the moment. Long term, I think we need
to define the elements of documentation, create tags and let Cocoon
transform them to the appropriate xhtml. After all isn't Coocon about
separating content from presentation?
Glen Ezkovich
HardBop Consulting
glen at hard-bop.com
A Proverb for Paranoids:
"If they can get you asking the wrong questions, they don't have to
worry about answers."
- Thomas Pynchon Gravity's Rainbow
