You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ctakes.apache.org by "Bleeker, Troy C." <Bl...@mayo.edu> on 2013/02/28 21:05:25 UTC
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
RE: 3.0 doc summary; one failing test
Posted by "Chen, Pei" <Pe...@childrens.harvard.edu>.
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
RE: 3.0 doc summary; one failing test
Posted by "Finan, Sean" <Se...@childrens.harvard.edu>.
+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
RE: 3.0 doc summary; one failing test
Posted by "Bleeker, Troy C." <Bl...@mayo.edu>.
> 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
RE: 3.0 doc summary; one failing test
Posted by "Chen, Pei" <Pe...@childrens.harvard.edu>.
> 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.atlassi
> > > 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
RE: 3.0 doc summary; one failing test
Posted by "Bleeker, Troy C." <Bl...@mayo.edu>.
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.atlassi
> > 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
RE: 3.0 doc summary; one failing test
Posted by "Chen, Pei" <Pe...@childrens.harvard.edu>.
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
RE: 3.0 doc summary; one failing test
Posted by "Bleeker, Troy C." <Bl...@mayo.edu>.
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
RE: 3.0 doc summary; one failing test
Posted by "Masanz, James J." <Ma...@mayo.edu>.
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
RE: 3.0 doc summary; one failing test
Posted by "Chen, Pei" <Pe...@childrens.harvard.edu>.
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.jira.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