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-Masanz.James=mayo....@incubator.apache.org > > [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.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:[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
