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:16:51 GMT

On Jun 10, 2005, at 3:38 PM, Ross Gardler wrote:

> Leszek Gawron wrote:
>
>> Linden H van der (MI) wrote:
>>
>
> ...
>
>
>> It would be the best if you provided your guideline as a template  
>> page YourPageShouldLookLikeThis.
>>
>
> It would be even better if you defined classes for the different  
> style elements you want and disable the ability to arbitrarily use  
> <em> and <i> for example.
> The htmlArea plugin can be customised so that the drop down menu  
> has things like:
>
> Instruction
> Code
> screenOutput
> Command
>
> etc.


I'm not sure removing the ability use these tags is wise. While we  
need conventions for our documentation we do need to allow for in- 
lining italics and bold so that an author can emphasize a point. I  
think the advantage to the specialized tags is that we can do thing  
that really make instructions, code, text, expected output, etc.  
stand out. Indenting and using different background colors or boxes  
can do wonders.


>
> (NB this is something I need to do for my own work soon, the Daisy  
> team have already pointed me at how to do it). I'll write up a  
> document for them when I've figured out the rest. May be a month or  
> so before I get time though.
>
> You shuold also look into created specific document types for  
> things like FAQ's, HowTo's user documentation etc. I have a set of  
> document types that I use like this. It makes for much more  
> structure to your documents, which ultimately makes them more useful.

Agreed. Templates will make it easier for new documentarians. One of  
the things I've done is define document types and created forms for  
their input. Obviously a next step. It doesn't fit every case but  
certainly faqs can be broken into questions and answers.


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