cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [Daisy/Docs] Styling conventions
Date Fri, 10 Jun 2005 22:51:12 GMT
Linden H van der (MI) wrote:
>>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.
> 
> 
> This is already taken care of in Daisy by the htmlArea plugin and
> Daisy's HTMLCleaner

The HTMLCleaner is great, but in my view it doesn't go far enough 
consider this:

It is really important.

It is <i>really</i> important.

It is <em>really</em> important.

All legal, all inconsistent. At least one not in line with the style 
guide you suggest.

Still, it's the least important point from my mail.

>>The htmlArea plugin can be customised so that the drop down menu has 
>>things like:
>>
>>Instruction
>>Code
>>screenOutput
>>Command
> 
> 
> This is a good idea.
> 
> 
>>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.
> 
> 
> Yes. I've been thinking about that. Even labeling documents with flags
> like 'tutorial' 'beginner' etc. would be sufficient for now.
> I don't have the privileges to set it up, so I'll bug Steven about it
> when we figure out what should be done. ;-)

Anyone with admin rights can set up the necesary configuration. So 
perhaps we need to decide who should have admin rights (I'd suggest 
committers who also want to be editors).

For the flags part, there is a multivalued field. You can add keywords 
(such as 'user', 'developer', 'beginner', 'advanced' etc.) and assign 
them to each document. You can then create index pages using the query 
language by searching on the keywords.

If you have sensible document types you can then create, for example, an 
index of tutorials for advanced developers with a simple little query.

I wouldn't use the keywords approach for identifying the diffferent 
document types, because the advantage of document types is that you can 
have different parts for different types of document. e.g. a FAQ just 
has a question (the document title), and an answer, but a HowTo has an 
abstract, a pre-requisites, a body, a summary a further reading section.

The advantage will be obvious, I am sure. You can do things like crete a 
"trail" through the How-To's be parsing all the entries in the 
pre-requisites section, or you can provide a "reminder sheet" that just 
has the summaries from all begineer tutorials etc.

This approach is working really well for an internal project here.

Ross

Mime
View raw message