You are viewing a plain text version of this content. The canonical link for it is here.

Posted to dev@deltaspike.apache.org by Ron Smeral <rs...@redhat.com> on 2015/04/08 01:19:37 UTC

DS Core documentation boost

Hi all,

we discussed this today with Rafael and Gerhard on IRC: it's about time 
we improved the state of documentation of DS (core)! There's still a lot 
of gaps to fill, the work progress is tracked here:
https://cwiki.apache.org/confluence/display/DeltaSpike/DS-Core+Overview 
(JIRA: https://issues.apache.org/jira/browse/DELTASPIKE-813)

I suggest the following mode of operation:
- sort the items by importance, then "sort" (just mentally, cwiki 
doesn't seem to allow secondary sort criterion) by the documentation 
status field
- choose the most important, least documented item
- mark the item as "WIP" (grey) in cwiki, so that we don't clash
- push the change (or PR), then mark as "OK" in cwiki
- repeat :)

Alternatively, we could split the work by topics. The biggest gaps seem 
to be around
- exception handling
- config (DeltaSpikeConfig, TypedConfig, BaseConfigPropertyProducer, ...)
- JSF
- CDI extension stuff (immutable bean, bean builder, contextual 
lifecycle, ...)
- utils (AnnotationUtils, ReflectionUtils, ServiceUtils, ...)
- JMX support

Thanks for any help!

Regards,
Ron

-- 
Ron Smeral
JBoss Quality Engineer
Brno

Re: DS Core documentation boost

Posted by Gerhard Petracek <ge...@gmail.com>.

+1 for an "advanced"-section.
we had something similar at codi, however, splitting the content isn't
always that easy.

regards,
gerhard



2015-04-08 18:48 GMT+02:00 Rafael Benevides <be...@redhat.com>:

> Thanks Ron for your perspective and help.
>
>
> I also would like to add some thoughts:
>
> - Due to the size and nature of DeltaSpike, people will only be able to
> know about a feature if it's mentioned on the documentation, that's why
> it's very important for DeltaSpike.
>
> - Anyway, a polluted documentation may also make the documentation hard to
> read.
>
> - My feeling is that some features that have low importance for users and
> lacks of proper documentation, should be placed in a kind of "advanced"
> section.
>
> - I agree with your "modus operandi" to fill the gaps on core
> documentation.
>
>
> On 4/7/15 19:19, Ron Smeral wrote:
>
>> Hi all,
>>
>> we discussed this today with Rafael and Gerhard on IRC: it's about time
>> we improved the state of documentation of DS (core)! There's still a lot of
>> gaps to fill, the work progress is tracked here:
>> https://cwiki.apache.org/confluence/display/DeltaSpike/DS-Core+Overview
>> (JIRA: https://issues.apache.org/jira/browse/DELTASPIKE-813)
>>
>> I suggest the following mode of operation:
>> - sort the items by importance, then "sort" (just mentally, cwiki doesn't
>> seem to allow secondary sort criterion) by the documentation status field
>> - choose the most important, least documented item
>> - mark the item as "WIP" (grey) in cwiki, so that we don't clash
>> - push the change (or PR), then mark as "OK" in cwiki
>> - repeat :)
>>
>> Alternatively, we could split the work by topics. The biggest gaps seem
>> to be around
>> - exception handling
>> - config (DeltaSpikeConfig, TypedConfig, BaseConfigPropertyProducer, ...)
>> - JSF
>> - CDI extension stuff (immutable bean, bean builder, contextual
>> lifecycle, ...)
>> - utils (AnnotationUtils, ReflectionUtils, ServiceUtils, ...)
>> - JMX support
>>
>> Thanks for any help!
>>
>> Regards,
>> Ron
>>
>>
>

Re: DS Core documentation boost

Posted by Rafael Benevides <be...@redhat.com>.

Thanks Ron for your perspective and help.


I also would like to add some thoughts:

- Due to the size and nature of DeltaSpike, people will only be able to 
know about a feature if it's mentioned on the documentation, that's why 
it's very important for DeltaSpike.

- Anyway, a polluted documentation may also make the documentation hard 
to read.

- My feeling is that some features that have low importance for users 
and lacks of proper documentation, should be placed in a kind of 
"advanced" section.

- I agree with your "modus operandi" to fill the gaps on core documentation.

On 4/7/15 19:19, Ron Smeral wrote:
> Hi all,
>
> we discussed this today with Rafael and Gerhard on IRC: it's about 
> time we improved the state of documentation of DS (core)! There's 
> still a lot of gaps to fill, the work progress is tracked here:
> https://cwiki.apache.org/confluence/display/DeltaSpike/DS-Core+Overview (JIRA: 
> https://issues.apache.org/jira/browse/DELTASPIKE-813)
>
> I suggest the following mode of operation:
> - sort the items by importance, then "sort" (just mentally, cwiki 
> doesn't seem to allow secondary sort criterion) by the documentation 
> status field
> - choose the most important, least documented item
> - mark the item as "WIP" (grey) in cwiki, so that we don't clash
> - push the change (or PR), then mark as "OK" in cwiki
> - repeat :)
>
> Alternatively, we could split the work by topics. The biggest gaps 
> seem to be around
> - exception handling
> - config (DeltaSpikeConfig, TypedConfig, BaseConfigPropertyProducer, ...)
> - JSF
> - CDI extension stuff (immutable bean, bean builder, contextual 
> lifecycle, ...)
> - utils (AnnotationUtils, ReflectionUtils, ServiceUtils, ...)
> - JMX support
>
> Thanks for any help!
>
> Regards,
> Ron
>