Community
Participate
Working Groups
Hi, Documentation of the ECF is fragmented. We need a central place for at least a users guide and a programmers/integration guide (t1). There must be a single source (t2) from where all forms of documentation can be generated (t3) like PDF, Eclipse help, etcetera, but there may not be a barrier to block contributions like commit access or specialized tools to create the documentation (t4). Specialized tools may be used to transform documentation to other forms of documentation. All public accessible existing documentation should be integrated into the new documents or be removed (t5). We must agree on a form of versioning (t6) that is functional but not intrusive. This can be to copy the documentation after each release or use some kind of @since construct that gets parsed by the documentation builder (t7) The format of the guides must be sober and fixed (t8) which aims to avoid endless topics and subtopics and enables the document builders to do some checking.
http://wiki.eclipse.org/DocumentationGuidelines/CrowdSourcingExample Provides info for topic t2.
Start of users guide: http://wiki.eclipse.org/EUG:Users_Guide Explanation of this manual: http://wiki.eclipse.org/EUG:How_to_Contribute
Start of integrators guide: http://wiki.eclipse.org/EIG:Integrators_Guide Do we need, an Example Guide?
I promised Scott I'd try to help out on this.
I will contribute on ECF Call API, SIP Imple, etc.
hi thanks for being on this bug. We have opened a page here [1] to vote for topics to start on first. Please take a look at it and add a point to the topics that you find interesting. This will help us sort out the priorities. [1]http://wiki.eclipse.org/ECF_Documentation_Priorities#Documentation_Area
@harshana, @james, @remy, @robert, @markus, @scott can you please list all the topics that you are able to work on. So that we can divide some work amongst us. We do not have to work on this full-time but just take one topic and really document it. The format of the manuals is explained here [1]. The format of the manuals will be guarded by me. Don't be shy if you're not sure about the format, we can correct all that afterwards. It is really the content that matters. If you start working on a topic, please annotate this topic with your name so that nobody else will start working on it. See an example here [2]. Also describe your efforts on this bug. [1] http://wiki.eclipse.org/EUG:How_to_Contribute [2] http://wiki.eclipse.org/EUG:Users_Guide#Introduction
Thanks to Wim (in particular) and everyone that's joined this bug for joining in on our ongoing attempts to make ECF easier and more useful for consumers. I think we've reached a point where ECF's software is *extremely* useful for lots of important use cases...e.g. Eclipse-based developer collaboration, OSGi servers/SOA/Remote Services, RCP applications that need messaging/communications (for both user visible and user invisible inter-process communications) and this makes the need for better/more/more comprehensive documentation, tutorials, and examples more For some time, I've wanted to create an ECF book. I think there's more than enough content and community interest to justify such a thing...and the only reason I haven't spent more effort making that happen is that I haven't had the personal resources to work on it while moving ECF forward engaging in enough paying work to support my family. I would like to revive the work on an ECF book, however, and use this Documentation project to do so. My vision for an ECF book has always been one based upon 'community authorship'...i.e. not having a single or even a small group of authors, but rather many authors...i.e. 'crowd sourcing' the actual book contents. One thing to contemplate for this documentation project: could we have this effort result in an an ECF book? I would very much like to see this as a result...so that people that wanted to consume the docs, tutorials, examples in book form could do so, and those that wanted to access it in other forms (e.g. wiki, web, source code control, etc) could also do so. I'm not yet sure how the publishers (Addison-Wesley does a number of Eclipse books) would treat such an effort, but it would be my intention to have some arrangement where many people could be credited with authorship. I don't have any expectation of receiving royalties myself, and would pledge to contribute any royalties that actually were to result from an ECF book back into the ECF project (to support further development, further documentation creation, hardware/software for testing, etc). So...I'm hopeful that this documentation project can move us all toward an ECF book (in addition to great online documentation), and that all of you will find the prospect of being an author appealing. Thanks for your continued support of ECF and it's community.
(In reply to comment #8) Sounds great Scott. Thanks. An idea, for the manuals, it would be nice if we had some combined RCP application with all of the user functions that ECF provides. What about the ECF-Hub RCP application (inspired by Tweethub) where Tweethub, chat clients and Newsreader come together in one big ECF proof of concept application. Tweethub, Salvo and Chat could then be the spokes of the hub. If we work on this together, it could possibly have some effect on the polish of the individual application which are all halve baked currently AND serve as a great example application for both the user manual and the integrators guide. more work, but an attractive app. Just a crazy idea, tell me what you think.
I will have a crack at SharedObject API, Distributed EventAdmin and Discovery API, which is what I have used. As long as people don't mind correcting my mistakes! Robert
I can probably chip away at the section on IRC.
(In reply to comment #10) > I will have a crack at SharedObject API, Distributed EventAdmin and Discovery > API, which is what I have used. As long as people don't mind correcting my > mistakes! No we don't mind at all. Thanks for helping. If you want you can also deliver the documentation in some format like word or whatever. If you know mediawiki please feel free to edit the wiki directly. The place for you to start editing is here: http://wiki.eclipse.org/EIG:Introduction_to_the_Shared_Object_API which is linked from here: http://wiki.eclipse.org/EIG:Integrators_Guide#The_Shared_Object_API If you want to alter the topic list, please look at the wiki source on the main page, but there is also an inclusion on the main link. The current topic list looks currently like this. The Shared Object API << this link aggregates the underlying topics Introduction to the Shared Object API << The pointer above Creating a Shared Object << I made this up could/should be different Sharing the Shared Object << idem dito
(In reply to comment #11) > I can probably chip away at the section on IRC. Thanks Remy. I guess the IRC has two faces, one for the users and one for the integrators. There is currently no topic for IRC in the integrators guide. If you want you can create one. If you want to start with the users guide then here is a starting link. http://wiki.eclipse.org/index.php?title=EUG:Introduction_to_IRC Which links from here http://wiki.eclipse.org/EUG:Users_Guide#IRC_-_Internet_Relay_chat If you want you can alter the topic list so that IRC is described the best. Again, if you want to deliver content in word/text/etc. instead of hacking the wiki directly then please go ahead.
As you can see, there is currently a lot of content scattered over the ecf wiki. There is also content in github here: https://github.com/ECF/ecf-nonepl/tree/master/modules/book/1st-edition/ We can re-use everything that is in these sources. If you do and if possible, please post a link to the original content.
Hi All, I will document the ECF Call API and ECF SIP Provider. I will cover the API, architecture and usage for integrations. I will improve the existing user guide for SIP provider for users. If time permits,I may be able work on Jingle as well. Thanks, Harshana
During yesterday's con call the question popped up under which license the documentation has to be contributed. This is especially important if the documentation project intents to eventually publish a book.
(In reply to comment #16) > During yesterday's con call the question popped up under which license the > documentation has to be contributed. This is especially important if the > documentation project intents to eventually publish a book. Please note the "Eclipse.org Terms of Use" which includes the content on the wiki. http://www.eclipse.org/legal/termsofuse.php
(In reply to comment #17) > Please note the "Eclipse.org Terms of Use" which includes the content on the > wiki. > http://www.eclipse.org/legal/termsofuse.php Indeed, this works for content that is contributed via the wiki. But not for all other contributions.
So where are we WRT licensing? I'm going to try to summarize...this isn't intended to b 'official' in any way, but rather my interpretation (so please correct if it's not right) If we use the Eclipse Wiki, then my understanding is that all materials are automatically under the EPL as per the terms of use here: http://www.eclipse.org/legal/termsofuse.php I guess the main practical question is this: Should we/ECF setup some additional wiki (or other contribution mechanism) to allow people to contribute ECF documentation (i.e. actual content associated with this project), or is this going to be necessary? I'm beginning to think that in order to make contribution to ECF documentation easier for more contributors (allowing other licenses...like creative commons, or other licenses) that it might make sense to have an ECF documentation-project-specific wiki, where the contribution/licensing/copyright would be determined by the needs of the project, rather than the EF organization. Other's perspectives on licensing, technologies for contribution (e.g. Eclipse Wiki, ECF-specific Wiki, etc)? My desire is to begin work on some of the documentation items soon. I haven't yet consulted the prioritized list http://wiki.eclipse.org/ECF_Documentation_Priorities to find the topics that I'm going to initially work on...please if you haven't prioritized things yourself go to the page above and do so now. Thanks. Also encourage others to do so as well. Thanks.
I would go ahead with the Integrators "OSGi Remote Service" chapter now, is this okay? Someone else already working on it?
I have aggregated and updated all existing wiki entries into the new OSGi Remote Service documentation [1][2][3]. I would consider moving the following still existing wiki entries [4][5][6][7][8][9] somewhere else (old?) and setting a link from the start page of the ECF project to the documentation (probably at first directly to OSGi Remote Services section only). I still need to set some links to javadocs and examples, and also will do the Discovery and Topology Management chapter this week. Please give feedback about any errors or additional information that should be provided - or edit by yourself. You can also use the wiki "Discussion" for this... Martin [1] http://wiki.eclipse.org/EIG:Introduction_to_OSGi_Remote_Services [2] http://wiki.eclipse.org/EIG:Runtime_Dependencies/Configuration [3] http://wiki.eclipse.org/EIG:Remoting [4] http://wiki.eclipse.org/OSGi_4.2_Remote_Services_and_ECF [5] http://wiki.eclipse.org/Using_ECF_Remote_Services_Bundles_separate_from_the_ECF_SDK [6] http://wiki.eclipse.org/Getting_Started_with_ECF%27s_OSGi_Remote_Services_Implementation [7] http://wiki.eclipse.org/Getting_Started_with_ECF%27s_RFC119_Implementation [8] http://wiki.eclipse.org/Getting_Started_with_Using_the_ECF_Remote_Services_API [9] http://wiki.eclipse.org/ECF/Asynchronous_Remote_Services
Excellent work Martin! Thanks. I have made some minor changes in order to stay tuned with the "how to contribute" guidelines (0). I hope you don't mind. I have moved the section of downloading ecf to the designated topic in the beginning of the manual (4). Headings: There is some inconsistency. For example, in the index of the manual, one topic is named "Service Distribution" but the page it points to is called "Remoting" and the text starts with the heading "Creating an OSGI Service Bundles". We should be consistent in page namings. I have added a "Remoting" introduction but I have not yet changed the index, but this need to be done. I am fine with the term "Remoting". The index I created was just to get us started. The same is true for "Runtime Dependencies/Configuration". I have left some comments here on what I think should be changed. Levels: In the "how to contribute guide" I have set a limit to the number of levels we can use to three. This is to avoid that every little paragraph gets its own entry in the TOC of the book. When I read your content, I think we must allow level 4 headings as well. I have edited your content to remove level two headings where they were not allowed (this is the topic level) but I have not added level 4 headings. Please take a look at the TOC for the Remote Services chapter to see if you are content with the heading levels. Please introduce level 4 headings OR remove in appropriate level three headings and format them with e.g. <b><big>Heading</big></b>. When I was reading your work, I noticed a couple of other things we should be aware of when writing this documentation. I have made a transclusion for the chapter. You can see it by clicking on the "remote services" chapter in (4). Addition to Standards 0. I have made every first header in the topic a link (see 5 and click on the heading of the chapter). This links back to the main manual. This will enable easy navigation. A "back" button in the page will also show when printing and aggregating. This is ugly. I am not really happy with the solution. What do you think. 1. You make use of the <source lang="java"> </source> directive which will format code the way the eclipse editor formats java code. I have added this to the how to contribute guide (1) 2. You make use of a nice table formatting template. This I have also added to the contribute guide (2) Things to Discuss / Be Aware Of 1. The use of hyperlinking in some places to blogs etcetera. If we want to make a book of this stuff, or need to print this in some way this will be difficult to handle. How should we handle this? 2. Describing things that will outdate really soon: For example, if we describe that we at least need Eclipse 3.6M5 to install ECF 3.3. This information will be old and confusing in no time. How should we handle this? (0) http://wiki.eclipse.org/EUG:How_to_Contribute (1) http://wiki.eclipse.org/EUG:How_to_Contribute#Formatting_Java_code (2) http://wiki.eclipse.org/EUG:How_to_Contribute#Using_Tables (3) http://wiki.eclipse.org/EIG:Runtime_Dependencies/Configuration (4) http://wiki.eclipse.org/EIG:Integrators_Guide (5) http://wiki.eclipse.org/EIG:Introduction_to_OSGi_Remote_Services Thanks again for the content. Regards, Wim
I have updated the "Introduction" section of the EIG (ECF Integrators Guide). Updated the download topic, added the download source code topic. I have also moved existing distributed event admin documentation to the EIG and updated this to use git instead of cvs. If someone has a lost 30 minutes, please help me to explain the source code tree. Stub text is in place and needs to be replaced by normal text.
Resetting target milestone to empty (no target milestone), as this is an ongoing effort.
creating 'ECF Providers' added : JGroups, JMS entries
updated jgroups provider doc at [0] [0] http://wiki.eclipse.org/EIG:JGroups_provider#A_sample_JGroups_client_container
Hi Pierre-Henry, Thank you for your contribution to the documentation project. I have included your JGroups section into a new chapter in the EIG [0]. First, I like the way you have outlined the provider in the "container instantiation" , "JGroups use", etc.. This has inspired me to create a template provider page here [1]. Scott would you say that this template page is sufficient to describe a container provider? About me: I know nothing about the JGroups protocol nor what you can use it for. So I am the perfect candidate to be educated by your jgroups provider page. The scope of the manuals is to learn non-ecf committers and even non-eclipse people on how to use the ECF modules. You deliver a description of the jgroups provider that assumes too much knowledge from the reader. [2] The page requires an introduction to jgroups. What is it, what problem does it solve and how does it solve it. I suggest that this is added under the JGroups provider heading. Section JGroups Container Instantiation: talks about an extension point. Can you provide screenshots ([[image:eig_screen.png]]) and explain how this extension point should be used? JGroups use: Does this work on a client computer only? What must be done on computer one and what must be done on computer two. Is there a server required? A Sample JGroups Client Container: The code snippets you provide miss context. What needs to be implemented for the code snippet to work. You talk about distributed event admin. How do we need to set that up in order to be used with jgroups? I assume that events can be sent with the JGroup protocol but how is this achieved? Is the need of the distributed event admin required in order for this provider to be used? What functionality does the container implementation provide? I hope you don't mind my remarks. Regards, Wim [0] http://wiki.eclipse.org/EIG:Integrators_Guide [1] http://wiki.eclipse.org/EIG:Example_Provider [2] http://wiki.eclipse.org/EIG:Who_should_use_this_guide
Ping: Harshana, Robert and Remy. When can we expect the start of your contribution?
(In reply to comment #28) > Ping: Harshana, Robert and Remy. When can we expect the start of your > contribution? Wim, I'll try to complete it by this week. Hope it's fine.
For everyone's info... In preparation for ECf 3.5 release, I've so far added several wiki pages...designed with trying to get people up and running with ECF Remote Services/RSA as quickly/easily as possible. Intalling OSGi Remote Services: http://wiki.eclipse.org/Installing_OSGi_Remote_Services Remote Services Admin: http://wiki.eclipse.org/Remote_Services_Admin I'm still working on the Remote Services Admin page, and will be for a few more days, I expect. And I've made significant changes to these previously-existing wiki pages: File-based Discovery: http://wiki.eclipse.org/File-based_Discovery Getting Started with OSGi Remote Services: http://wiki.eclipse.org/ECF/Getting_Started_with_OSGi_Remote_Services Getting the Hello Example Service: http://wiki.eclipse.org/Getting_the_Hello_Example_Service ECF Servers: http://wiki.eclipse.org/ECF/Servers I'm not sure how best to integrate with the ECF documentation project effort with these new pages...and need some guidance/discussion about how best to do this. thanks.
Thanks Sott! Great work. I will integrate it into the EIG and let this bug know when it is finished.
updated EIG:Jgroups provider see [0] 0] http://wiki.eclipse.org/EIG:JGroups_provider#JGroups_Provider
updated EIG:Jgroups provider see [0] [0] http://wiki.eclipse.org/EIG:JGroups_provider#JGroups_Provider
(In reply to comment #33) > updated EIG:Jgroups provider see [0] > > > [0] http://wiki.eclipse.org/EIG:JGroups_provider#JGroups_Provider Excellent work Pierre! Very user friendly documented. I will follow your steps as a user to see if I can get the jgroups going.
updated EIG:Jgroups provider see [0] Added UI feature. [0] http://wiki.eclipse.org/EIG:JGroups_provider#JGroups_Provider
Nice work Pierre. Apart from the integrators guide, there is also a users guide. Some or all of the UI work could go in there too. I did some work in the users guide already: http://wiki.eclipse.org/EUG:Users_Guide
I've added a fair amount of additional content to the Remote Services Admin wiki page: http://wiki.eclipse.org/Remote_Services_Admin. I would appreciate any review/comments, etc...as I make additions and edits. Thanks.
As promised I created a small wikipage on the usage of the RemoteServiceAdminListener interface here. [0] This is my first time helping an Eclipse project. I hope the page complies with all standards and guidelines. [0] http://wiki.eclipse.org/EIG:RemoteServiceAdminListener
(In reply to comment #38) > As promised I created a small wikipage on the usage of the > RemoteServiceAdminListener interface here. [0] > > This is my first time helping an Eclipse project. I hope the page complies with > all standards and guidelines. > > [0] http://wiki.eclipse.org/EIG:RemoteServiceAdminListener Thanks kindly Patrick...this is excellent...and is a terrific contribution to ECF. Please consider yourself an ECF contributor...and welcome to the team :). Again...many thanks. If you can, please do consider helping with additional docs, bug reports, feature requests, examples, tutorials, etc. I've added a link to this page to the Remote Services Admin page: http://wiki.eclipse.org/EIG:Remote_Services_Admin#RemoteServiceAdminListener_for_Synchronous_Notification
> [0] http://wiki.eclipse.org/EIG:RemoteServiceAdminListener Added to the main index. Thank you for your contribution.
This page should be removed or marked as deprecated: http://wiki.eclipse.org/Discovery_and_Distribution_Listeners Had to chase down the IHostDistributionListener file in your Git repo to find out from the change history that it had been removed in favour of RSA.
(In reply to comment #41) > This page should be removed or marked as deprecated: > http://wiki.eclipse.org/Discovery_and_Distribution_Listeners > > Had to chase down the IHostDistributionListener file in your Git repo to find > out from the change history that it had been removed in favour of RSA. Thanks. I've removed the content of the page, and put a link to RSA, and removed the two links to this page as well.
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. 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.
In response to comment 43 I've reorganized the ECF main wiki page. See http://wiki.eclipse.org/ECF Here's a short summary of the changes: Moved OSGi Remote Services up to the top (to avoid confusion with the ECF meeting/conferencing information) Created sub-categories underneath OSGi Remote Services: Introductory Materials Dounload and Install More Advanced Usage of OSGi Remote Services Remote Service Admin Customization of ECF Remote Services Created a new introductory tutorial: Building your first OSGi Remote Service http://wiki.eclipse.org/Tutorial:_Building_your_first_OSGi_Remote_Service More introductory and/or more advanced tutorials to come as well. My hope is that this reorganization will (particularly) help newcomers to find appropriate material for understanding and using OSGi Remote Services/RSA. Other/additional changes could be made, so please comment here if you think additional changes are warranted. Further suggestions and areas for clarification most appreciated.
Objections to moving "ECF Documentation Project" & "Other Cool Stuff" before "ECF calls and Meetings"? Then everything documentation related comes in a row.
(In reply to Markus Kuppe from comment #45) > Objections to moving "ECF Documentation Project" & "Other Cool Stuff" before > "ECF calls and Meetings"? Then everything documentation related comes in a > row. +1
(In reply to Scott Lewis from comment #46) > (In reply to Markus Kuppe from comment #45) > > Objections to moving "ECF Documentation Project" & "Other Cool Stuff" before > > "ECF calls and Meetings"? Then everything documentation related comes in a > > row. > > +1 I reorganized the page into two major sections: "Documentation" and "Development". The former links to everything relevant for consumers, while the latter targets committers (might as well rename to "consumers" and "committers"?).
