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:[email protected]] > Sent: Friday, March 01, 2013 4:23 PM > To: [email protected] > 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:[email protected]] > Sent: Friday, March 01, 2013 3:31 PM > To: [email protected] > 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- > [email protected] [mailto:ctakes-dev-return- > [email protected]] On Behalf Of Chen, > Pei > Sent: Friday, March 01, 2013 1:54 PM > To: [email protected] > 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:[email protected]] > > Sent: Friday, March 01, 2013 2:11 PM > > To: [email protected] > > 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- > > [email protected] [mailto:ctakes-dev-return- > > [email protected]] On Behalf Of Chen, > > Pei > > Sent: Friday, March 01, 2013 12:53 PM > > To: [email protected] > > 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:[email protected]] > > > Sent: Friday, March 01, 2013 12:31 PM > > > To: '[email protected]' > > > 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- > > > [email protected] > > > [mailto:ctakes-dev-return- > > > [email protected]] On Behalf Of > > Masanz, > > > James J. > > > Sent: Friday, March 01, 2013 11:21 AM > > > To: '[email protected]' > > > 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- > > [email protected] > > > > [mailto:ctakes-dev-return-1307- > > > > [email protected]] On Behalf Of Chen, > > Pei > > > > Sent: Friday, March 01, 2013 8:20 AM > > > > To: [email protected] > > > > 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:[email protected]] > > > > > Sent: Thursday, February 28, 2013 3:06 PM > > > > > To: [email protected] > > > > > 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 * [email protected] > > > Mayo > > > > > Clinic * 200 First Street SW * Rochester, MN 55905 * > > > > www.mayoclinic.org
