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
