geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jason Dillon <ja...@planet57.com>
Subject Re: [DISCUSS] Tracking documentation tasks in JIRA ( was Re: [RTC] Clarification please from the PMC )
Date Sat, 01 Jul 2006 05:46:05 GMT
> There have been JIRAs for commits/RTCs where in the mailing list  
> they have been described as a major enhancement, yet the JIRA does  
> not even have a description or comments.  The lack of information  
> about the changes in the JIRA makes it harder for others to review  
> the change.  Developers should not assume that they will just be  
> able to explain their change via IRC to those reviewing it.   
> Everyone isn't in a suitable timezone to chat with the developer  
> making the change.  More documentation needs to be placed in the  
> JIRAs and the Wiki.

I agree that JIRA should track the relevant details.  Sometimes those  
details are discussed in IRC.  When that happens I recommend that the  
relevant snips of the chat be added to the related issues as comments.


> All code change JIRAs should have adequate information in them for  
> people to be able to review and test a change.  This information  
> can then be used as a seed for documenting the changes in further  
> detail in the wiki/manuals (if the change impacts end users).  Any  
> enhancement/change that should be discussed in the manuals should  
> have another JIRA created for the documentation task for it.

+1


> FOR DISCUSSION:
>
> 1. Any change that end users may have visibility of should have a  
> documentation task JIRA created for it and the documentation JIRA  
> task should be linked to the JIRA for the change.  Examples of  
> these are:

Mixed feelings about this...

I think that its good to have more visibility/oversight on  
documentation and how it relates to code changes...

But I think that this might be a bit much.

I'd rather see that the code change JIRA have enough description or  
comments to be used as the basis for new documentation and explain  
the details of the change for release notes.   And for major changes  
have a per-release page in the wiki to track more human readable  
notes perhaps with references to issues or other detail pages.

I really like how Atlassian tracks their notes with Confluence and  
use the {jiraissues} macro to include JIRA issues in the detail pages:

     http://confluence.atlassian.com/display/DOC/Release+Notes

I'd recommend following this style for release notes.  I setup a  
similar policy at the last company I was at and it worked out quite  
well for about 5 different groups working on about 12 different  
projects.

Anyways, I like the idea of more documentation oversight... but  
concerned that we try and keep it simple.  IMO adding a new  
documentation issue seems to add significant complexity and overhead,  
which may end up degrading the overall flow of documentation.

--jason

Mime
View raw message