[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[ecf-dev] Documentation project: call for participation

Hi Folks,

As many of you probably realize, ECF's documentation is lacking. We have upwards of 10 excellent APIs, and although in most cases we have working tests, working examples, and javadocs for these APIs, we still don't have nearly enough documentation (e.g. overviews...architectural and otherwise...tutorials, example apps, snippets, articles, blogs, slides, presentations, use cases, etc). Thanks tomany, we now actually have a fair amount of wiki-based docs, examples, slides, etc...but I think nearly everyone would agree that it is not enough.

I would like to include in our Indigo plan an item to specifically address this in a concerted way over the next 7 months (before Indigo release).

This is, however, going to take the effort of the entire ECF community. ECF is not corporate controlled (yay!), so we have very few resources at our disposal (for anything...from development to releng to documentation). To meet the needs and desires of our rapidly growing community, we need to ask for support from our community. Not support via payment/money...but rather support via participation and contributions. I think of this as 'crowd-sourcing'...asking for participation and contribution from many, in order that all may benefit from the cooperation.

Contributing to documentation is a great, very low-cost way to contribute to ECF...and at the same time to make ECF more accessible and usable to yourself and others. Documenting does not have to be in full 'article' or 'book chapter' form...it can be very short (e.g. 1-2 paragraphs) about some use case, or some subtlety in an API. It can also be working on organizing existing docs (e.g. creating a remote services examples page and linking to existing examples), or providing outlines or assisting one of the committers or contributors in doing these things. It can be a blog posting(s), responding to mailing list or forum questions, or aggregating questions/answers into a faq. All of these are terrific contributions.

To kick this off, I've created a section in the wiki that points to two pages for the ECF documentation project [1].

In that section is the ECF documentation project enhancement request [2], and a page that lists some of the possible areas for priority focus for documentation attention [3].

If you are reading this, and agree that ECF would be more valuable to you with more/better documentation, I would ask that you do two things to help out:

a) Add yourself to the bug at [2]
b) Go to [3] and increment the number beside the areas that you think are particularly important...and/or add new areas that aren't currently listed.


This way we can get a handle on which areas people feel most need docs, and begin to coordinate around how to address those needs in the best way possible.

Thanks much,

Scott

[1] http://wiki.eclipse.org/Eclipse_Communication_Framework_Project#ECF_Documentation_Project
[2] https://bugs.eclipse.org/bugs/show_bug.cgi?id=329124
[3] http://wiki.eclipse.org/ECF_Documentation_Priorities