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 22:46:33 GMT
Sounds good.
Maybe it'll make more sense to me once we have an end user application/GUI like Open Office
(hopefully soon).
--Pei

> -----Original Message-----
> From: Finan, Sean [mailto:Sean.Finan@childrens.harvard.edu]
> Sent: Friday, March 01, 2013 4:23 PM
> To: ctakes-dev@incubator.apache.org
> Subject: RE: 3.0 doc summary; one failing test
> 
> +1 for separate (but parallel) User and Dev guides.
> 
> I could provide a lot of long-winded reasoning, but I'll just leave you with my
> vote and the opinion that parallelization of any such two guides is pretty
> important.
> 
> -----Original Message-----
> From: Bleeker, Troy C. [mailto:Bleeker.Troy@mayo.edu]
> Sent: Friday, March 01, 2013 3:31 PM
> To: ctakes-dev@incubator.apache.org
> Subject: RE: 3.0 doc summary; one failing test
> 
> > In order for me choose, I have to read both just to understand what
> > the difference
> I disagree. The Getting Started page (and other places) spell out the
> difference in just a couple sentences. Reading the Install Guides won't help
> you decide your use case.
> > is because I am both ... in the current state, I think both users and
> > developers are the same
> I see. You've nailed the heart of the difference. I believe there is a non-
> arbitrary use case for a person as a binary-only user (even if for a temporary
> period of time). They are not a developer and therefore need their own
> information.
> > Why not just a single guide?
> Because of that use case. So if the community as a whole thinks that use case
> does not exist then it could be reworked.
> 
> Thanks
> Troy
> 
> -----Original Message-----
> From: ctakes-dev-return-1312-
> Bleeker.Troy=mayo.edu@incubator.apache.org [mailto:ctakes-dev-return-
> 1312-Bleeker.Troy=mayo.edu@incubator.apache.org] On Behalf Of Chen,
> Pei
> Sent: Friday, March 01, 2013 1:54 PM
> To: ctakes-dev@incubator.apache.org
> Subject: RE: 3.0 doc summary; one failing test
> 
> > Getting Started page, realize they want to kick the tires, and head
> > off to the User Install Guide
> I agree with this, but what is proposed is: Quick Start Guide and then a fork:
> Do I Choose User Guide OR Developer Guide.  The fork is what is confusing...
> I am a new user:  Where do I start?  I have to choose if I am a "User" or a
> "Developer".
> In order for me choose, I have to read both just to understand what the
> difference is because I am both a user and a developer.  Why not just a single
> guide?  To me, in the current state, I think both users and developers are the
> same which is probably causing the confusion.  If the only difference is bin vs.
> src then why can't the guide just specific, "To compile from source...do xzy"
> rather than have to guess arbitrary roles?
> 
> --Pei
> 
> > -----Original Message-----
> > From: Bleeker, Troy C. [mailto:Bleeker.Troy@mayo.edu]
> > Sent: Friday, March 01, 2013 2:11 PM
> > To: ctakes-dev@incubator.apache.org
> > Subject: RE: 3.0 doc summary; one failing test
> >
> > I could see the User Guide that way but not the Developer Guide. They
> > both describe this - "setup, get stuff, configure stuff, test stuff".
> > There is a few comments about why things are happening and what it
> > means but they are few. To me they are just install guides not
> > manuals. A manual would go through things like why you would use one
> > component over another, how you hook them up, what is dependent on
> > what and why, ways to sift through and utilize the output, use cases,
> > spelled out examples (Andy mentioned), and more.
> >
> > So, said another way, you think it's too high a hurdle for a newcomer
> > to read the Getting Started page, realize they want to kick the tires,
> > and head off to the User Install Guide? Not sure what to say except I
> > don't think so. Perhaps getting newcomer opinions would be best.
> >
> > Thanks
> > Troy
> >
> > -----Original Message-----
> > From: ctakes-dev-return-1310-
> > Bleeker.Troy=mayo.edu@incubator.apache.org [mailto:ctakes-dev-return-
> > 1310-Bleeker.Troy=mayo.edu@incubator.apache.org] On Behalf Of Chen,
> > Pei
> > Sent: Friday, March 01, 2013 12:53 PM
> > To: ctakes-dev@incubator.apache.org
> > Subject: RE: 3.0 doc summary; one failing test
> >
> > 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.atlas
> > > > si an .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