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 Thu, 15 Feb 2007 11:19:32 GMT
Aight... I've re-crafted this page, have a look:

     http://cwiki.apache.org/geronimo/tips-for-writing-and-formatting- 
documentation.html

--jason


On Feb 14, 2007, at 2: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 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