geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hernan Cunico <hcun...@gmail.com>
Subject Re: [CONF] Apache Geronimo Documentation: Tips for writing and formatting documentation (page edited)
Date Wed, 14 Feb 2007 22:43:44 GMT
As I said before, my idea for that doc was not to show all the options Confluence offer but
how to apply some of those formats specifically on the Geronimo documentation.

Please, feel free to update the document with the format you think would be easier to understand.
That was just my vision for explaining these formats consistently applied to a specific case.

Others pls chime in with your opinions too, the more comments the better. Ultimately, the
goal is to provide a clear message of how to format an article in a consistent way with the
rest of the documentation.

Cheers!
Hernan

Jason Dillon wrote:
> 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