Re: [ecf-dev] Better ECF documentation (Re: ECF Feature Restructuring)

[Scott Lewis <slewis@xxxxxxxxxxxxx>]

Hi Pablo,

Your comments and suggestions are certainly appreciated...and will be acted upon. 

We (and the community) would greatly appreciate any help that you can/would be willing to provide...and all the committers understand that ECF contributors are not as familiar with the details of the various parts of ECF.    OTOH...as Markus says:  people who are less familiar with things can/will provide very important insight for those of us that are more familiar.  

Particularly WRT to documentation changes/contributions, what I would like to suggest we do to coordinate is:

1) Join the ECF documentation sub project bug:  https://bugs.eclipse.org/bugs/show_bug.cgi?id=329124 (I've added a comment to this bug with your observations and comments).
2) When you have some time to contribute to the documentation, either
    a) open a new bug/enhancement...and make 329124 dependent upon this new bug
or b) Add a comment that you are going to work on a certain part of the docs/links on bug 329124

I would suggest that if it's a significant change, that you do 'a' rather than 'b'...if at all possible. 

If you would like to ask any of the committers:  myself, Markus, Wim, Harshana, etc...about the changes you are proposing...then please also send a quick note to this mailing list...and we will do everything to comment and respond...even if it's just +1 (go!).   Also...feel free to contact any of us via email...and we can/could consult with you directly...i.e. via phone, email, conference call, hangout, etc. to coordinate...and notify you of other things that could possibly be reused.

>As another suggestion, have you thought about in writing a book with all the
>available information? I think many people would be interested in buy it.

Actually...yes we have thought about this...and discussed it some.  Thank you for publicly communicating your interest in such a thing.  

The problem for some of us currently is resources (time).    None of us currently has full sponsorship to undertake such a thing (i.e. we need to work at other things to support ourselves), although if there are people in range of this that could help with that...please say so. :). 

We are...however...slowly moving in those directions... WRT OSGi remote services in particular (RSA, discovery, distribution, providers, rest, soap, etc., etc)...and it remains my hope that we will be able to complete a book and support work (e.g. examples, tutorials, etc) over the next 1.5 years.   It's also my hope that this is something like a 'community-created' book...where not only I and other committers create sections, but also there are contributions from consumers (e.g. use cases) and contributors.   FWIW, I am personally not expecting any income from such an effort but will be doing whatever I can to

IMHO there is more than enough useful content to go into a book...from content about general issues of using OSGi Services for SOA (dynamics and reliability, network failure, sync/async), to using ECF...i.e. using existing providers, to EventAdmin/group messaging, to customizing ECF's RSA, and/or extending and/or creating new providers for specific/distributed use cases.  Again...IMHO there's lots to talk about :).  The trouble for me and other currently is:  getting the necessary time to do so.

Thanks,

Scott

On 12/4/2013 9:27 AM, Pablo García Sánchez wrote:

Of course, I will help (within my means, because I am not an expert ;)

2013/12/4 Markus Alexander Kuppe <ecf-dev_eclipse.org@xxxxxxxxxxx>

On 12/04/2013 02:12 PM, "Pablo García Sánchez" <fergunet@xxxxxxxxx>" wrote:
> Hi guys. I would suggest centralize all tutorials and information in the
> Integrator's Guide [1] or publicity this wiki more. There are several
> tutorials in Scott's blog or other webs [2], but I think that the
> "official" source of documentation should be the wiki, and newcomers
> should find the wiki easy to find and navigate. For example, a link to
> [2] from [1].
>
> Some clarification should be performed. For example. which tutorial
> should be used to start: [3] or [4]? Also, some pending subsections
> should be redacted (the ones in red in [1]).
>
> Also, if you enter in the ECF main page [5] you see the "Getting Started
> Thing" [6] with some comments, and then an user enters in the ECF wiki,
> but the first thing that sees is the conference calls info. New users
> need to move to "New Stuff" section with a lot of unordered issues to
> find the Integrator's Guide.
>
> Finally, some interesting sections (such as [7]) are not located in a
> visible part of the web (for example, the EIG does not include a link to
> [7]).
>
> [1] https://wiki.eclipse.org/EIG:Integrators_Guide
> [2] http://www.eclipse.org/community/eclipse_newsletter/2013/july/article3.php
> [3] https://wiki.eclipse.org/EIG:Remoting
> [4] https://wiki.eclipse.org/EIG:Getting_Started_with_OSGi_Remote_Services
> [5] http://www.eclipse.org/ecf/
> [6] http://www.eclipse.org/ecf/gettingStarted.php
> [7] http://wiki.eclipse.org/SOAP-based_Providers
>
> Summarizing, there are a lot of information about how to use ECF, but it
> is a bit disorganized and difficult to find.

Hi Pablo,

you are absolutely right that most of ECF's documentation is scattered
around the place and that it hinders adoption. Would you be willing to
help us to clean up/restructure the wiki (after all its editable by
everybody with an EF account)?

Btw. with sufficient resources, we would also be happy to re-design the
ECF website which doesn't exactly follow today's style in website design.

Thanks
Markus
_______________________________________________
ecf-dev mailing list
ecf-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/ecf-dev

--
Pablo García Sánchez
Departamento de Arquitectura y Tecnología de Computadores
Universidad de Granada
http://geneura.ugr.es/~pgarcia

_______________________________________________
ecf-dev mailing list
ecf-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/ecf-dev