incubator-ctakes-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Bleeker, Troy C." <Bleeker.T...@mayo.edu>
Subject RE: Apache Confluence wiki for documentation?
Date Wed, 26 Sep 2012 22:12:02 GMT
I looked at the markdown syntax of the ASF CMS that is where the cTAKES Apache site is built.
Using this for doc would mean migration from our existing Confluence. Internet search revels
this is not straight forward. Others have issues with broken tables and what was macros. We
don't need the macros much but the tables are key to the existing doc.

ASF CMS also has editing/staging/production. While it sounds nice, there is a lag between.
Maybe not big but if we don't need the function... Confluence has version control for every
single change that is made. You can revert back easily.

The WYSIWYG editor is super limited with markdown syntax ASF CMS. Tables don't even exist.

Since we have a previous Confluence investment and due to the differences noted above, could
I suggest/ask that we go ahead with requesting the ASF Confluence be set up? (Reopen https://issues.apache.org/jira/browse/INFRA-5185)
We should only need an export from the old and import to the new. I have done this with Confluence
before as long as I have admin access. Close version proximity of Confluence would be good
though. cTAKES doc is currently in a Confluence 4.0 setup. This would at least get us started
as opposed being on the fence in discussion. We can continue the discussion of ship/no ship
of doc in parallel.

Thanks
Troy
-----Original Message-----
From: ctakes-dev-return-422-Bleeker.Troy=mayo.edu@incubator.apache.org [mailto:ctakes-dev-return-422-Bleeker.Troy=mayo.edu@incubator.apache.org]
On Behalf Of Chen, Pei
Sent: Monday, September 24, 2012 10:59 AM
To: ctakes-dev@incubator.apache.org
Subject: RE: Apache Confluence wiki for documentation?

Good points... I wonder if we could easily take an export/snapshot of the online .mdtext,html,wiki,
etc. version during build/release time.  If it seems reasonable, we could investigate creating
a script or maven goal to export from the content /site/ directory as an example (assuming
content is there; which is probably more important than the delivery mechanism at this point)?
Just throwing out the option...  

My biggest pet peeve in the past with open software is that detailed technical documentation
never seems to be up-to-date with code that I end up just viewing the source anyway.  But
a simple/general end user guide, quick start examples, FAQ's/known gotchas, are always helpful.
My 1/2 cent- but I'll leave it up to the experts/volunteers in this realm...

> -----Original Message-----
> From: Jörn Kottmann [mailto:kottmann@gmail.com]
> Sent: Saturday, September 22, 2012 5:43 PM
> To: ctakes-dev@incubator.apache.org
> Subject: Re: Apache Confluence wiki for documentation?
> 
> There are always smaller issues coming up when you release something. 
> If there is a bigger issue the best thing in my experience is to just 
> release again and get it fixed. Doesn't matter if it is something in 
> your software or the documentation. For me its important that i can 
> easily access the documentation for the software version I am running.
> 
> When I use Open Source software which is not super stable yet and I 
> have an issue I usually try out the trunk version and see how things 
> work there, so in that case I would likely see your documentation update.
> 
> Jörn
> 
> On 09/14/2012 04:39 PM, Bleeker, Troy C. wrote:
> > Would you still say that if you knew that an issue with the product 
> > you just
> spent 2 hours trying to work-around something could have been avoided 
> if you were looking at the latest documentation? The difference in 
> "ease of access" is minor, no?
> >
> > Thanks
> > Troy
> >
> > -----Original Message-----
> > From: ctakes-dev-return-388-
> Bleeker.Troy=mayo.edu@incubator.apache.org
> > [mailto:ctakes-dev-return-388-
> Bleeker.Troy=mayo.edu@incubator.apache.o
> > rg] On Behalf Of Jörn Kottmann
> > Sent: Friday, September 14, 2012 9:27 AM
> > To: ctakes-dev@incubator.apache.org
> > Subject: Re: Apache Confluence wiki for documentation?
> >
> > On 09/14/2012 04:19 PM, Masanz, James J. wrote:
> >> I also prefer to not distribute the documentation with the release.
> > I actually prefer to have the documentation included in the 
> > distribution,
> because then I can always easily access the documentation which 
> matches the version I am working with and do not have to go somewhere to find it.
> >
> > Jörn


Mime
View raw message