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 2012/11/06 21:14:49 UTC
First documentation pages
All,
I'd like to start creating the pages that will become the documentation and the starting points. This may be more at once than you'd like to consider but here are the changes I see considering who we said before our users are. Don't freak out if you see the changes starting. They can always be reverted or changed... please comment on any, all, or part of these:
* Migration from Confluence was harder than anticipated due to mis-matched versions. More investigation shows that ASF has installed plug-ins to the Apache CMS which make markdown more palatable. Building is yet an unknown, at least I have not tried yet.
* Move Getting Started under GENERAL, so it appeals to everyone who first sees the site. It will define our users and point them in the right direction.
* Download should list a fast path to all downloads per release. Like we mentioned: the source code, one large JAR, etc. It should be very short and point users to full doc elsewhere.
* Glossary - I already added and populated with the glossary from the NIH Confluence wiki.
* Move Incubator Page, License, and History under COMMUNITY. These are less frequently accessed comparatively. Under GENERAL we want the first things a new-to-the-site persons considers going to.
* Community FAQs - not sure there really are any yet. The one that is there is covered under the User and Developer sections. Would like to remove for now.
* Add a Developer Guide instead of Source Code. The Downloads page will have fast path to code but we need a launching place for all-things-developer.
* Having Bug Tracker under DEVELOPERS suggests that users should not use it. I don't think that's true. Obviously the mailing lists are used if possible but if a user knows we have a bug then they can report it. Let's move under COMMUNITY.
* So USERS and DEVELOPERS would have a guide and FAQs, nothing else. The guide would have a main summary page followed by links to the top level of each release's guide.
Now a question as well. When we went from cTAKES 1.0 to 1.2 we settled on calling the parts of cTAKES one can take advantage of "component" as evidenced by the diagram created and the documentation section headers, etc. In the past month I've seen more people refer to the cTAKES parts as "module". I'm not stuck on a name. Perhaps module is more of a maven term and we didn't have that before. I have in mind what I like, but as I said it does not really matter to me, so long as we are consistent. If we change away from "component" the doc we pull over from previous releases will need to be modified, also not too big a deal. What do you think?
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: First documentation pages
Posted by Steven Bethard <st...@Colorado.EDU>.
On Nov 6, 2012, at 9:14 PM, "Bleeker, Troy C." <Bl...@mayo.edu> wrote:
> Now a question as well. When we went from cTAKES 1.0 to 1.2 we settled on calling the parts of cTAKES one can take advantage of "component" as evidenced by the diagram created and the documentation section headers, etc. In the past month I've seen more people refer to the cTAKES parts as "module". I'm not stuck on a name. Perhaps module is more of a maven term and we didn't have that before. I have in mind what I like, but as I said it does not really matter to me, so long as we are consistent. If we change away from "component" the doc we pull over from previous releases will need to be modified, also not too big a deal. What do you think?
I've been saying "module" only in specific reference to the Maven modules. I don't have any preference at all as to what we call the different parts of cTAKES in the documentation. (Except of course when we're literally talking about Maven modules, and there, of course, we should say "module".)
Steve
RE: First documentation pages
Posted by "Chen, Pei" <Pe...@childrens.harvard.edu>.
I would suggest whatever would be easier for the person to update and maintain... I presume the former?
> -----Original Message-----
> From: Bleeker, Troy C. [mailto:Bleeker.Troy@mayo.edu]
> Sent: Thursday, November 08, 2012 6:45 PM
> To: ctakes-dev@incubator.apache.org
> Subject: RE: First documentation pages
>
> Do we need to separate cTAKES documentation versions from one another?
> For example, if we tried to build the doc, should the files all be contained
> within one top level folder or is it OK to simply use file names as distinction
> and let them all be in the same folder. I would guess the former but would
> like some guidance.
>
> Thanks
> Troy
> -----Original Message-----
> From: ctakes-dev-return-818-
> Bleeker.Troy=mayo.edu@incubator.apache.org [mailto:ctakes-dev-return-
> 818-Bleeker.Troy=mayo.edu@incubator.apache.org] On Behalf Of Chen, Pei
> Sent: Tuesday, November 06, 2012 4:15 PM
> To: ctakes-dev@incubator.apache.org
> Subject: RE: First documentation pages
>
> > * Move Getting Started under GENERAL, so it appeals to everyone
> who
> > first sees the site. It will define our users and point them in the
> > right direction.
> I think the Getting Started section should be extremely simple- something
> like:
> (I think the component diagram/dependency tree should be in the manual or
> reference appendix rather than "quick" start guide).
>
> Requirements
> -----------
> Java 1.6+ is required to run cTAKES
>
> Download
> -----------
> [Link to the latest download section to apache-ctakes-{release}.tar.gz/.zip]
> and unzip file.
>
> Running the default pipeline in the UIMA CAS Visual Debugger or Collection
> Processing Engine
> -----------
> Run bin/runctakesCVD/CPE.sh.bat
> Load AE (analysis engine)
> Select desc/ctakes-clinical-
> pipeline/desc/analysis_engine/AggregatePlaintextProcessor
> Enter note(s) and run analysis engine.
>
> Notes
> -----------
> If you plan to use the UMLS Resources, on can add the umls user info:
> Export/set ctakes.umlsuser=[username]
> Export/set ctakes.umlspw=[password]
> or add the system properties to the java args -Dctakes.umlsuser=[username]
> -Dctakes.umlspw=[password]
>
> > Now a question as well. When we went from cTAKES 1.0 to 1.2 we settled
> > on calling the parts of cTAKES one can take advantage of "component"
> > as evidenced by the diagram created and the documentation section
> > headers, etc. In the past month I've seen more people refer to the
> > cTAKES parts as "module". I'm not stuck on a name. Perhaps module is
> > more of a maven term and we didn't have that before. I have in mind
> > what I like, but as I said it does not really matter to me, so long as
> > we are consistent. If we change away from "component" the doc we pull
> > over from previous releases will need to be modified, also not too big a
> deal. What do you think?
>
> If we had references to 'component' in the previous documentation, my
> vote would be to also keep it as component; introducing a new term would
> probably just add more confusion to users.
>
> --Pei
RE: First documentation pages
Posted by "Bleeker, Troy C." <Bl...@mayo.edu>.
Do we need to separate cTAKES documentation versions from one another? For example, if we tried to build the doc, should the files all be contained within one top level folder or is it OK to simply use file names as distinction and let them all be in the same folder. I would guess the former but would like some guidance.
Thanks
Troy
-----Original Message-----
From: ctakes-dev-return-818-Bleeker.Troy=mayo.edu@incubator.apache.org [mailto:ctakes-dev-return-818-Bleeker.Troy=mayo.edu@incubator.apache.org] On Behalf Of Chen, Pei
Sent: Tuesday, November 06, 2012 4:15 PM
To: ctakes-dev@incubator.apache.org
Subject: RE: First documentation pages
> * Move Getting Started under GENERAL, so it appeals to everyone who
> first sees the site. It will define our users and point them in the
> right direction.
I think the Getting Started section should be extremely simple- something like:
(I think the component diagram/dependency tree should be in the manual or reference appendix rather than "quick" start guide).
Requirements
-----------
Java 1.6+ is required to run cTAKES
Download
-----------
[Link to the latest download section to apache-ctakes-{release}.tar.gz/.zip] and unzip file.
Running the default pipeline in the UIMA CAS Visual Debugger or Collection Processing Engine
-----------
Run bin/runctakesCVD/CPE.sh.bat
Load AE (analysis engine)
Select desc/ctakes-clinical-pipeline/desc/analysis_engine/AggregatePlaintextProcessor
Enter note(s) and run analysis engine.
Notes
-----------
If you plan to use the UMLS Resources, on can add the umls user info:
Export/set ctakes.umlsuser=[username]
Export/set ctakes.umlspw=[password]
or add the system properties to the java args -Dctakes.umlsuser=[username] -Dctakes.umlspw=[password]
> Now a question as well. When we went from cTAKES 1.0 to 1.2 we settled
> on calling the parts of cTAKES one can take advantage of "component"
> as evidenced by the diagram created and the documentation section
> headers, etc. In the past month I've seen more people refer to the
> cTAKES parts as "module". I'm not stuck on a name. Perhaps module is
> more of a maven term and we didn't have that before. I have in mind
> what I like, but as I said it does not really matter to me, so long as
> we are consistent. If we change away from "component" the doc we pull
> over from previous releases will need to be modified, also not too big a deal. What do you think?
If we had references to 'component' in the previous documentation, my vote would be to also keep it as component; introducing a new term would probably just add more confusion to users.
--Pei
RE: First documentation pages
Posted by "Chen, Pei" <Pe...@childrens.harvard.edu>.
> * Move Getting Started under GENERAL, so it appeals to everyone who
> first sees the site. It will define our users and point them in the right
> direction.
I think the Getting Started section should be extremely simple- something like:
(I think the component diagram/dependency tree should be in the manual or reference appendix rather than "quick" start guide).
Requirements
-----------
Java 1.6+ is required to run cTAKES
Download
-----------
[Link to the latest download section to apache-ctakes-{release}.tar.gz/.zip] and unzip file.
Running the default pipeline in the UIMA CAS Visual Debugger or Collection Processing Engine
-----------
Run bin/runctakesCVD/CPE.sh.bat
Load AE (analysis engine)
Select desc/ctakes-clinical-pipeline/desc/analysis_engine/AggregatePlaintextProcessor
Enter note(s) and run analysis engine.
Notes
-----------
If you plan to use the UMLS Resources, on can add the umls user info:
Export/set ctakes.umlsuser=[username]
Export/set ctakes.umlspw=[password]
or add the system properties to the java args
-Dctakes.umlsuser=[username] -Dctakes.umlspw=[password]
> Now a question as well. When we went from cTAKES 1.0 to 1.2 we settled on
> calling the parts of cTAKES one can take advantage of "component" as
> evidenced by the diagram created and the documentation section headers,
> etc. In the past month I've seen more people refer to the cTAKES parts as
> "module". I'm not stuck on a name. Perhaps module is more of a maven term
> and we didn't have that before. I have in mind what I like, but as I said it does
> not really matter to me, so long as we are consistent. If we change away
> from "component" the doc we pull over from previous releases will need to
> be modified, also not too big a deal. What do you think?
If we had references to 'component' in the previous documentation, my vote would be to also keep it as component;
introducing a new term would probably just add more confusion to users.
--Pei