geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matt Hogstrom <>
Subject Re: [CONF] Apache Geronimo Documentation: Tips for writing and formatting documentation (page edited)
Date Sun, 18 Feb 2007 17:07:18 GMT
I think providing the overal scheme for writing doc will help people  
out immensely in that there is a pattern to follow.  I'll need to go  
though it a little bit more and try my hand but this is a good step  


On Feb 14, 2007, at 5:43 PM, Hernan Cunico wrote:

> 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  
>> or 
>> +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

View raw message