geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jason Dillon <ja...@planet57.com>
Subject Re: [CONF] Apache Geronimo Documentation: Tips for writing and formatting documentation (page edited)
Date Wed, 14 Feb 2007 21:53:02 GMT
On Feb 14, 2007, at 5:54 AM, Hernan Cunico wrote:
> Jason Dillon wrote:
>> This style of page is not really very easy to  read... as it  
>> basically tosses out any use of any markup... and does not link to  
>> urls, etc...
>
> That's the whole point, so you can see how to the wiki markup  
> should used. Otherwise you would be seeing just the end result  
> (which you can also see by looking to any other doc anyway) and  
> will have to check the page source (edit) to see how it is  
> implemented.

Um, you are missing *my point* Hernan, that *most* of the content on  
that page is *not* wiki markup, but explanations on how to use the  
markup, with small examples of wiki markup.

Because you have wrapped the entire content in a big {noformat} then  
*nothing* else inside can use wiki notation, and it won't render  
URLs... so the URLs you added for http://www.openoffice.org or http:// 
confluence.atlassian.com/display/CONFEXT/Gliffy+Plugin+for+Confluence 
+-+Diagram+and+draw+in+Confluence simply don't render as links.

This style is also hard to read... since you can't differentiate  
sections of the tips very well.

My recommendation is still, to *not* use a *big* {noformat} for *all*  
of the content, but to only wrap the wiki notation examples with  
{noformat}, and let the rest make use of the mark up to help organize/ 
display the content better.

--jason



Mime
View raw message