forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: Glossary
Date Sat, 08 Apr 2006 23:42:11 GMT
Gav.... wrote:
> I notice I can not add code examples to the Glossary, should I limit the
> Glossary to descriptions only with links to code examples then? 

In my opinion, a glossary is not intended to be any kind of tutorial or 
example. It should only give a concise definition and a link to more 
complete documentation.

The problem with allowing too much detail in a glossary is that it then 
becomes "just another place" for documentation to go. The more places we 
have for documentation, the more fragmented that documentation becomes.

> It would have been nice to have even an inline or one line code snippet.

I am -0 on allowing code snippets in glossary entries. I would rather 
the effort went into ensuring the main docs were complete and linking to 
them from the glossary.

Others may disagree.

Ross

Mime
View raw message