ctakes-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew McMurry <mcmurry.a...@gmail.com>
Subject Re: Proposal: Using JIRA to track and request changes to documentation
Date Wed, 04 Dec 2013 21:23:22 GMT
Troy: completely agree, and great job on the docs !

[ ** Revised proposal ** ]

* committers use JIRA for doc issues as you see fit but not required for every doc change

* ctakes-user  requested doc changes  ( helps maintain FAQ) 

DOC issue priority 

* Blocker: critical doc missing or wrong, for example the User Guide is missing 
* Major: doc is a incomplete and a frequently asked question, for example UMLS setup 
* Minor: doc improvement, for example using more concise language to describe a complex topic
like components   
 

On Dec 4, 2013, at 12:29 PM, "Bleeker, Troy C." <Bleeker.Troy@mayo.edu> wrote:

> Troy deserves a little credit too :) ...
> 
> I agree with the JIRA issues for big context changes, but would caution that doing so
could create a dumping ground for little issues that really should be changed by anyone in
the community who notices.  If you see an issue in the doc and it's relatively minor and you
know the answer, then change the page.
> 
> Troy
> 
> -----Original Message-----
> From: dev-return-2279-Bleeker.Troy=mayo.edu@ctakes.apache.org [mailto:dev-return-2279-Bleeker.Troy=mayo.edu@ctakes.apache.org]
On Behalf Of Masanz, James J.
> Sent: Wednesday, December 04, 2013 2:22 PM
> To: 'dev@ctakes.apache.org'
> Subject: RE: Proposal: Using JIRA to track and request changes to documentation
> 
> I agree completely about using JIRA for documentation and about adding Documentation
as an Issue Type (looks like JIRA has such a predefined type that we have not enabled within
Apache cTAKES JIRA)
> 
> -----Original Message-----
> From: dev-return-2277-Masanz.James=mayo.edu@ctakes.apache.org [mailto:dev-return-2277-Masanz.James=mayo.edu@ctakes.apache.org]
On Behalf Of Tim Miller
> Sent: Wednesday, December 04, 2013 2:12 PM
> To: dev@ctakes.apache.org
> Subject: Re: Proposal: Using JIRA to track and request changes to documentation
> 
> Sounds like a good idea to me. Good for tracking major issues, especially for targeting
future releases and making sure we get the things done we say we will. Unless there is any
way this dramatically violates some convention I don't see why not!
> Tim
> 
> On 12/04/2013 03:11 PM, Andrew McMurry wrote:
>> Hi all
>> I'll have an update about the VM situation shortly (positive news) but in the meantime
I propose a new issue type in JIRA: doc.
>> 
>> The ctakes docs are very good, and James deserves a lot of credit. 	
>> User docs are as important as code, sometimes even more so.
>> It is therefore appropriate to track how documentation is being updated with release
versions.
>> 
>> Example of DOC issues worth tracking in JIRA:
>> * "Confluence home page still refers to version 3.0 by default"
>> * "User FAQ should state recommended JVM memory size"
>> * "User FAQ should point to UMLS setup instructions"
>> 
>> As an added benefit, each time we do a release we can see if the docs need to be
updated accordingly.
>> I am *NOT* proposing that every change to documentation requires a JIRA ticket.
>> But we should have a mechanism to record doc issues.
>> 
>> Do you agree with the proposal?
>> 
>> --AndyMC
> 


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message