Feature explanations belong in JIRA, with links here

[Bertrand Delacretaz <bd...@apache.org>]

Hi,

I see quite a lot of emails on this list that explain new features in
detail - this is cool, but IMO it would be much better to have that info in
JIRA, and only or mostly pointers here.

As an example from another project, SLING-550 describes a feature that I
implemented in Sling, which is not officially documented but you can find
all the required info in there to use it: use case, how to activate and
test the functionality, etc.

If you want to use Sling background servlets, I can just tell you to go
look at SLING-550. No need to hunt in mailing lists and even if you need to
you can search for the "SLING-550" string as a unique feature ID.

Having such a "master issue" for each new feature, which describes (or
points to) usecases, installation and test information, all with permanent
URLs, is IMO much more valuable than email scattered around. Such an issue
is often good enough as documentation, as we won't reach our dream of
correctly documenting everything soon.

Hope this helps,
-Bertrand

Re: Feature explanations belong in JIRA, with links here

[Bertrand Delacretaz <bd...@apache.org>]

On Monday, September 24, 2012, Fabian Christ wrote:

> ...remember that discussions should take place on the list. There are
> other projects who discuss features using the JIRA comment feature.
> Personally, I do not like that approach. It is more efficient to do
> discussions here and describe the reached consensus in a JIRA issue...

Absolutely agree, thanks for clarifying! In the end I think what's
important to have in JIRA (or another suitable place with a permanent URL)
is a description of the use case and of how to activate/test a given
feature.

-Bertrand

Re: Feature explanations belong in JIRA, with links here

[Fabian Christ <ch...@googlemail.com>]

Hi Bertrand,

thanks for that suggestion. Sounds reasonable and IMO we should follow
that path.

But remember that discussions should take place on the list. There are
other projects who discuss features using the JIRA comment feature.
Personally, I do not like that approach. It is more efficient to do
discussions here and describe the reached consensus in a JIRA issue as
Bertrand suggested.

Best,
 - Fabian

2012/9/24 Bertrand Delacretaz <bd...@apache.org>:
> Hi,
>
> I see quite a lot of emails on this list that explain new features in
> detail - this is cool, but IMO it would be much better to have that info in
> JIRA, and only or mostly pointers here.
>
> As an example from another project, SLING-550 describes a feature that I
> implemented in Sling, which is not officially documented but you can find
> all the required info in there to use it: use case, how to activate and
> test the functionality, etc.
>
> If you want to use Sling background servlets, I can just tell you to go
> look at SLING-550. No need to hunt in mailing lists and even if you need to
> you can search for the "SLING-550" string as a unique feature ID.
>
> Having such a "master issue" for each new feature, which describes (or
> points to) usecases, installation and test information, all with permanent
> URLs, is IMO much more valuable than email scattered around. Such an issue
> is often good enough as documentation, as we won't reach our dream of
> correctly documenting everything soon.
>
> Hope this helps,
> -Bertrand



-- 
Fabian
http://twitter.com/fctwitt