cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Glen Ezkovich <g...@hard-bop.com>
Subject Re: [Daisy/Docs] Styling conventions
Date Fri, 10 Jun 2005 22:07:04 GMT
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


Mime
View raw message