[dna-dev] Re: JIRA and Wiki

[Randall Hauch]

It has been our policy that we create JIRA issues for each task and  
feature, and that those issues be where we capture discussions,  
requirements, and design notes for those bugs and features.

If a feature is large enough that it warrants documentation, then  
please add that documentation to the Reference Guide.  The docbooks  
are under source control, are updated and included in each release,  
and are available for multiple releases (so people can go back and  
reference older versions).  This is also what most new members/users  
will start with, so it should make sense to newbies but should be  
complete enough for reference material for experts.   (And the code  
should be well-documented.)

We often have discussions on IRC, but that's not captured  
automatically, so if something important is said, we usually capture  
the important bits and add to the JIRA (or send in an email to the  
group).

I hope we do not go down the road of documenting things in multiple  
places.  Generally JavaDocs have much more detail and are obviously at  
the code level, while the docbook content should be the higher-level  
descriptions.  I also hope we stay away from large design documents -  
we basically follow an agile approach and let the software evolve as  
the needs arise.  Yes, we have architectural goals, but those are  
hopefully covered in the official docs.

Personally, I'm not a huge fan of the wiki.  The new JBoss.org wiki is  
much better than the old one, it still has a lot to be desired.  Most  
people unfamiliar with the project will find it difficult to find  
things on the wiki.  And too many times I've seen the wiki pages get  
out of date.  Ours are probably already out of date.  However,  
considering that the new wiki is dramatically improved over the old  
one, I would be interested to hear everyone's opinion on it.

Thoughts?  Opinions?

Best regards,

Randall

On Nov 20, 2008, at 4:02 PM, Sergey Litsenko wrote:

> Hi All,
> A number of interesting ideas appeared in recent dna-dev digest  
> emails. While I'm not deleting my e-mails but I suppose I'm not the  
> only one who found it difficult to manage our design minutes and  
> proposals in e-mails.
>
> May I suggest something (as it also has being pointed out by Randall  
> in our discussions about JDBC graphs)?
>
> It would be nice to see summary of  your design proposals/ideas as a  
> JIRA tickets for future releases OR as comments to existing tickets  
> (where related/existed) PLUS links to your WIKI with details - so  
> your  ideas don't get lost in e-mail threads.  And we can vote on  
> these tickets and understand more about priorities and future plans  
> for components. Your detailed proposals and SDD can be managed by  
> JBoss Wiki. JIRA is a good place to record/track progress of  bugs  
> and new feature requests, and Wiki is a good place for our  
> collaboration and ideas.
>
> What do you think?
>
>
> Best regards,
>    Sergiy
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/dna-dev/attachments/20081120/645e22e6/attachment.html