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
