ctakes-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Chen, Pei" <Pei.C...@childrens.harvard.edu>
Subject RE: 3.0 doc summary; one failing test
Date Fri, 01 Mar 2013 18:53:26 GMT
Makes sense to me.  But would it make sense to have the below or just call it what it is:
1) A Quick Start Guide (download the bin, and runs thru some test docs) [What we currently
call a "user"?]
2) A cTAKES Manual [What we currently call "developer"?]

[Probably not the current release, but for the future consideration.  Having multiple types
of guides seems to require a user to think too much even to get started IMHO.] 
Just my 1/2 cent as a user and not a tech writer...

--Pei

> -----Original Message-----
> From: Bleeker, Troy C. [mailto:Bleeker.Troy@mayo.edu]
> Sent: Friday, March 01, 2013 12:31 PM
> To: 'ctakes-dev@incubator.apache.org'
> Subject: RE: 3.0 doc summary; one failing test
> 
> I agree with James' assessment. The Getting Started page defines users
> versus developers in this light. Users may end up being developers but there
> are people today who want to try it out without all the dev stuff. When they
> come from knowing nothing about cTAKES, I think running a couple docs
> through the CPE helps them learn. The User Install Guide is the only thing, for
> now, that helps facilitate new user adoption. So keep it and make it better in
> the future. Manage expectations by placing guiding wisdom into the doc,
> although as you know, we have install and reference material but no how-to
> doc so far.
> 
> The auto generated JIRA roadmap is limited in scope, as-in only points to
> release notes, and only has a one line description. But this does make more
> sense as an archive page, which as I said believe to be required. It only takes
> like 15 mins at the end of a release to put together. People prefer a short list
> of major improvements and then to drill down into release notes for details.
> 
> The only reason it was called roadmap was because it contained a future
> releases section where you could place what upcoming releases might have
> in them. JIRA takes the place of that so the page really is a better archive. So I
> linked this in as the Archives page under general. In the future new releases
> would replace what is on the Downloads page and what was on the
> downloads page would move to the archive page. This page is still the only
> page that has a short summary of the features in cTAKES 3.0 however. I think
> it needs to be somewhere else as well. Maybe downloads?
> 
> I'll respond to the structure question in a separate thread. It's not doc related
> anyway.
> 
> Thanks
> Troy
> 
> -----Original Message-----
> From: ctakes-dev-return-1308-
> Bleeker.Troy=mayo.edu@incubator.apache.org [mailto:ctakes-dev-return-
> 1308-Bleeker.Troy=mayo.edu@incubator.apache.org] On Behalf Of Masanz,
> James J.
> Sent: Friday, March 01, 2013 11:21 AM
> To: 'ctakes-dev@incubator.apache.org'
> Subject: RE: 3.0 doc summary; one failing test
> 
> 
> As far as user vs. developer guide.
> There have been people who want to just download a binary and run
> without compiling or even without an IDE - to 'kick the tires' a bit.
> 
> As far as the structures of binary vs source, at least one difference is the way
> XML descriptors are bundled together under one master desc directory
> rather than in within the separate components. Not sure if there was more
> that Troy was referring to.
> 
> -- James
> 
> > -----Original Message-----
> > From:
> > ctakes-dev-return-1307-Masanz.James=mayo.edu@incubator.apache.org
> > [mailto:ctakes-dev-return-1307-
> > Masanz.James=mayo.edu@incubator.apache.org] On Behalf Of Chen, Pei
> > Sent: Friday, March 01, 2013 8:20 AM
> > To: ctakes-dev@incubator.apache.org
> > Subject: RE: 3.0 doc summary; one failing test
> >
> > Do we need to differentiate between cTAKES developer guide and user
> > guide? I think in its current state,  cTAKES users are probably
> > developers.  Perhaps we should just combine them and just call it a
> > guide/manual just like UIMA?
> > I think once we have a tool that runs in the 3 steps that Andy
> > referred to, then I think that would be something an end-user would use...
> > (Probably not the current UIMA CPE/CVD GUI's.)  Just to manage some of
> > the expectations for those end-users.
> >
> > http://incubator.apache.org/ctakes/roadmap.html looks good, but will
> > need to be maintained manually vs: the roadman from Jira which is
> > automatically generated:
> > https://issues.apache.org/jira/browse/CTAKES#selectedTab=com.atlassian
> > .j ira.plugin.system.project%3Aroadmap-panel ?
> >
> > > - Agree on one structure for cTAKES projects. The binary
> > > distribution is in a different form that the developer source. We
> > > decided a long time ago to try something new. It never caught on in
> > > the developer ranks. We should either complete the transformation in
> > > dev or return the user binary structure to match dev.
> > I'm not quite sure what you mean here.  Each component is a separate
> > module in the source code. In the distribution binary, each component
> > is distributed with it's own jar in /lib now.  For example: ctakes-
> > assertion.jar, ctakes-core.jar.
> >
> >
> > > -----Original Message-----
> > > From: Bleeker, Troy C. [mailto:Bleeker.Troy@mayo.edu]
> > > Sent: Thursday, February 28, 2013 3:06 PM
> > > To: ctakes-dev@incubator.apache.org
> > > Subject: 3.0 doc summary; one failing test
> > >
> > > I think I've done as much as I can do on the doc at this point. I
> > > was able to run the Linux install/tests for both dev and user. For
> > > user, the results of the CVD run were basically nothing. There was
> > > but 1 annotation for all the text pasted in. No concepts. Nothing.
> > > If someone wants to verify this we could create a JIRA item. I may
> > > have
> > missed something.
> > >
> > > Otherwise (with completed items left out) here is what could still
> > > be
> > done:
> > >
> > > - The examples, as described by Andy, would be more than a readme
> > > should have. This would be great for a how-to guide. The Developer
> > > Guide and User Guide have been renamed to Install Guides. I don't
> > > think a how-to guide should be incorporated into these but should be
> > > its own document. Making one would be great and as you say should
> > > include things like 1) pointers to where to find basic information
> > > 2) very high level overview of the components in the context of
> > > using them to do a very basic task 3) I think it was suggested that
> > > the Getting Started page might be something like this in very short form.
> > > If we did that then it would point to a more comprehensive how-to
> > > guide. [The Getting Started page is a short start now.]
> > >
> > > - Project history page of all cTAKES releases placed on Apache sites
> > > somewhere. Good plan if short. I would not copy readmes there but
> > > have links to them. This was done in the past but removed from the
> > > bottom of the downloads page. This page exists now but is not linked
> > > to from the Apache cTAKES site. Here is a direct link:
> > > http://incubator.apache.org/ctakes/roadmap.html. Decide if you want
> > > to go forward with something like this. An archive page will be
> > > needed when we have more releases under our belt.
> > >
> > > - Creating a single download for a newcomer. We should revisit this
> > > at some point in order to make the best first impression. A new user
> > > should be able to get from nothing to running cTAKES in three steps:
> > > download, uncompress, run (like 2.5).
> > >
> > > - Agree on one structure for cTAKES projects. The binary
> > > distribution is in a different form that the developer source. We
> > > decided a long time ago to try something new. It never caught on in
> > > the developer ranks. We should either complete the transformation in
> > > dev or return the user binary structure to match dev. New users are
> > > potential new
> > developers of cTAKES in the future.
> > > It's confusing when those two structures are not the same for that
> > > person. If you want to attract contributions well ... this does not
> > help.
> > >
> > > Perhaps these could all be made JIRA items.
> > >
> > > Thanks
> > > Troy Bleeker * Senior Business Analyst CBAP(r) * Biomedical
> > > Statistics and Informatics
> > > Phone: 507-293-1574 * Fax: 507-284-0360 * bleeker.troy@mayo.edu
> Mayo
> > > Clinic * 200 First Street SW * Rochester, MN 55905 *
> > www.mayoclinic.org


Mime
View raw message