Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 299061

Summary:	Improve "Getting Started" documentation
Product:	[RT] ECF	Reporter:	Bill Michell <bill.michell>
Component:	ecf.doc	Assignee:	ecf.doc-inbox <ecf.doc-inbox>
Status:	CLOSED FIXED	QA Contact:
Severity:	normal
Priority:	P3	CC:	samolisov, slewis
Version:	unspecified	Keywords:	helpwanted
Target Milestone:	---
Hardware:	All
OS:	All
URL:	http://www.eclipse.org/ecf/gettingStarted.php
Whiteboard:

Description Bill Michell

2010-01-07 12:16:09 EST

Build Identifier: 

The "Getting Started" page at http://www.eclipse.org/ecf/gettingStarted.php is completely inadequate for a user coming to ECF for the first time and trying to figure out what they should do next.

It needn't contain everything someone needs, but it ought to at least link to something like the following content - or copy (or rewrite) various things inline.

Good links:
http://java.dzone.com/news/the-ecf-project-an-interview-w
http://www.ibm.com/developerworks/opensource/library/os-ecl-commfwk/ 

Part of the problem is that the team responsible for ECF seems to think of it as a framework that other developers will write tools for, that other developers might then use to do whatever it is they want to do in the first place. They are undoubtedly correct, of course, but I didn't find this distinction at all obvious.

I'd probably instead say something like the following:

ECF is a framework for supporting the development of distributed Eclipse-based tools and applications. It can be used to create other plugins, tools, or full Eclipse RCP applications that require asynchronous point-to-point or publish-and-subscribe messaging.

That means that ECF, per se, is a tool for people interested in writing add-ons for Eclipse (or Equinox, Eclipse's OSGi server) that require the ability to communicate across the network, whether peer-to-peer or client-server.

Around ECF, a number of things have been built - most notably the P2 update system that Eclipse 3.5 now uses for installing and updating Eclipse components and add-on features. This means that if you already have a recent Eclipse version, you already have, and have probably used, ECF.

Other features built on top of ECF include various Chat clients (including Google Talk, Skype and Jabber) and the collaborative editing feature DocShare, which allows you to share an editing window with somebody half-way around the world.

If you're considering starting using ECF, I'd strongly recommend you be using at least Eclipse 3.5, since the latest version of ECF (3.1) doesn't support earlier versions.

To get started with chat within Eclipse 3.5, or sharing your editing windows with a remote colleague, you just have to download the ECF SDK package, connect to your partner with Skype or XMPP (e.g. Google Talk or Jabber), and start communicating.

The ECF SDK update site for Eclipse 3.5 is at http://download.eclipse.org/rt/ecf/3.1/3.5/repo and instructions on sharing your editing window are at http://wiki.eclipse.org/DocShare_Plugin

When work first started on ECF, the capabilities of the publicly available chat servers were limited, so the team has also worked on a Generic Server application. However, as a beginner/user, you will probably find that you can get started as an ECF user without needing to set up a server of your own - use one of the servers mentioned above instead.

There are a number of additional plugins available from the update site at http://ecf1.osuosl.org/OSUrelease-repo/repo if the standard package doesn't support what you need to do.

If you are considering becoming an ECF developer, or want to search the mailing list archives, head over to the ecf-dev mailing list at https://dev.eclipse.org/mailman/listinfo/ecf-dev

ECF is not a corporate-member run or sponsored project, unlike most Eclipse Foundation projects, so any assistance you can give, whether through good bug reports, assistance with writing documentation, or contributions of code or even proprietary extensions would be greatly appreciated.

Reproducible: Always

Comment 1 Scott Lewis

2010-01-21 15:44:08 EST

Thanks.  I will be updating the overall getting started over the next few weeks.

What would also be of help is getting some input (and prose) about what parts of ECF are in most need (from your point of view) for getting started info...as ECF is now a number of things...i.e. example im/collaboration applications, remote services infrastructure, provider/protocol implementations, etc.

(In reply to comment #0)
> Build Identifier: 
> 
> The "Getting Started" page at http://www.eclipse.org/ecf/gettingStarted.php is
> completely inadequate for a user coming to ECF for the first time and trying to
> figure out what they should do next.
> 
> It needn't contain everything someone needs, but it ought to at least link to
> something like the following content - or copy (or rewrite) various things
> inline.
> 
> Good links:
> http://java.dzone.com/news/the-ecf-project-an-interview-w
> http://www.ibm.com/developerworks/opensource/library/os-ecl-commfwk/ 
> 
> Part of the problem is that the team responsible for ECF seems to think of it
> as a framework that other developers will write tools for, that other
> developers might then use to do whatever it is they want to do in the first
> place. They are undoubtedly correct, of course, but I didn't find this
> distinction at all obvious.
> 
> I'd probably instead say something like the following:
> 
> ECF is a framework for supporting the development of distributed Eclipse-based
> tools and applications. It can be used to create other plugins, tools, or full
> Eclipse RCP applications that require asynchronous point-to-point or
> publish-and-subscribe messaging.
> 
> That means that ECF, per se, is a tool for people interested in writing add-ons
> for Eclipse (or Equinox, Eclipse's OSGi server) that require the ability to
> communicate across the network, whether peer-to-peer or client-server.
> 
> Around ECF, a number of things have been built - most notably the P2 update
> system that Eclipse 3.5 now uses for installing and updating Eclipse components
> and add-on features. This means that if you already have a recent Eclipse
> version, you already have, and have probably used, ECF.
> 
> Other features built on top of ECF include various Chat clients (including
> Google Talk, Skype and Jabber) and the collaborative editing feature DocShare,
> which allows you to share an editing window with somebody half-way around the
> world.
> 
> If you're considering starting using ECF, I'd strongly recommend you be using
> at least Eclipse 3.5, since the latest version of ECF (3.1) doesn't support
> earlier versions.
> 
> To get started with chat within Eclipse 3.5, or sharing your editing windows
> with a remote colleague, you just have to download the ECF SDK package, connect
> to your partner with Skype or XMPP (e.g. Google Talk or Jabber), and start
> communicating.
> 
> The ECF SDK update site for Eclipse 3.5 is at
> http://download.eclipse.org/rt/ecf/3.1/3.5/repo and instructions on sharing
> your editing window are at http://wiki.eclipse.org/DocShare_Plugin
> 
> When work first started on ECF, the capabilities of the publicly available chat
> servers were limited, so the team has also worked on a Generic Server
> application. However, as a beginner/user, you will probably find that you can
> get started as an ECF user without needing to set up a server of your own - use
> one of the servers mentioned above instead.
> 
> There are a number of additional plugins available from the update site at
> http://ecf1.osuosl.org/OSUrelease-repo/repo if the standard package doesn't
> support what you need to do.
> 
> If you are considering becoming an ECF developer, or want to search the mailing
> list archives, head over to the ecf-dev mailing list at
> https://dev.eclipse.org/mailman/listinfo/ecf-dev
> 
> ECF is not a corporate-member run or sponsored project, unlike most Eclipse
> Foundation projects, so any assistance you can give, whether through good bug
> reports, assistance with writing documentation, or contributions of code or
> even proprietary extensions would be greatly appreciated.
> 
> Reproducible: Always

Comment 2 Scott Lewis

2010-06-06 21:06:48 EDT

Contributions welcomed to address this and other doc needs (of which there are many).

Comment 3 Scott Lewis

2014-02-12 13:56:55 EST

Thanks Bill for the observations and suggestions.

We've made a number of introductory changes to the ECF documentation...e.g. tutorials, etc...given changed focus to OSGi remote services.  

Resolving as fixed.   Additional documentation contributions most welcome.