Difference between revisions of "Samples and Walkthroughs"

(Overview (Working in progress))
m (Added category)
 
(39 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Overview (Working in progress) =
+
[[Category:Documentation]]
This page is dedicated to discussing the evaluation of Samples and Walk-through project.
+
= Overview =
 +
This page is dedicated to discussing the evaluation of Samples and WalkThrough project.
  
The project is designed to increase exposure of Eiffel in a multi-facet manner with both the expertise of in-house Eiffel Software developers and employee as well as the Eiffel community.  
+
The project is designed to increase exposure of Eiffel in a multi-facet manner with both the expertise of in-house Eiffel Software developers and employee as well as the Eiffel community. The samples will express everything for new syntax being released, show casing library/language research, help new users get to grips with Eiffel for the first time and help those already using Eiffel to take advantage of advanced concepts.
 +
 
 +
With a strong community affiliation samples will appear showing off Eiffel in domains Eiffel Software themselves have not conceived or using Eiffel in novel ways, as well as showing off Eiffel tips, tricks and practices to avoid.
  
 
= The Problem =
 
= The Problem =
Samples are not being produced at a rate to match changes in the Eiffel language so users outside of Eiffel Software are not always aware of new features or tips and tricks that make Eiffel a fantastic language platform. On the road map to ECMA compliance there are going to be a number of language additions that benefit all. Users are left with outdated or archic samples to base their projects on.
+
Samples are not being produced at a rate to match changes in the Eiffel language so users outside of Eiffel Software are not always aware of new features or tips and tricks that make Eiffel a fantastic language platform. On the road map to ECMA compliance there are going to be a number of language additions that benefit all. Users are left with outdated or archaic samples to base their projects on. Their use of Eiffel is marred instead of enriched.
  
Getting started with Eiffel is hard; there are small number of samples and tutorials dedicated to getting started with Eiffel, introducing the language and it's constructs. There are little walkthroughs to writing a first program using EiffelStudio, no samples for advanced concepts. As of today most samples and walkthroughs are attached to a Eiffel library and some libraries do not even have provided examples, forcing users to become hackers of sorts and read the library source code in order to figure out how to use it.
+
Getting started with Eiffel is harder than it should be; there are small number of samples and tutorials dedicated to getting started with Eiffel, introducing the language and it's constructs. There are little walkthroughs to begin writing a first program using EiffelStudio and no samples for advanced concepts. As of today most samples and walkthroughs are attached to a Eiffel library and some libraries do not even have provided examples, forcing users to become hackers of sorts by reading the library source code in order to figure out how to use it.
  
 
This needs to change!
 
This needs to change!
  
= Proposition ==
+
= Proposition =
 +
What is being proposed is that Eiffel Software provides a means to access samples, where it be through a client application (a stand-alone or through EiffelStudio) or via a web interfaces. In order for tools to be developed to support sample browsing, every sample should be attached to a description containing informative text and metadata for consumption by client tools.
  
What is being proposed is that Eiffel Software provides a means to access samples, where it be through a client application (a stand-alone or through EiffelStudio) or via a web interfaces. Samples should contains full descriptions, even an article, and be embedded with metadata for tools to consume. This metadata comes in the form of referenced technology (libraries, platform, etc), compiler version, descriptions, sample type and level.
+
= Project Roadmap =
 +
Below is the tentative roadmap for development. Each milestone represents a way point of completed development. Depending on time and resource each milestone will indicate a release.
  
As an extension, the new ECF format could be extended to reference sample URLs for instance access to associated samples on how to use the library
+
== Milestone 1 ==
 +
The first milestone is dedicate to creating the first version of a sample browser tool for use with a downloaded version of a Eiffel Software product.
  
= Proposed Metadata =
+
=== What Needs to be Done ===
  
Every sample created should be partnered with a sample description index file. The index file is to be used be client tool to display/hide samples based on user queries from such a tool. For instance a new user will most likely want only introductor samples and walkthroughs. If 100 samples are offered it would be a lot to wade through to find the applicable samples. In addition a new user want only those samples that pertain to learning the language and not any particular library.
+
* Before beginning any specification or design for any client tools a specification needs to be drawn up for a sample index file. This specification is being worked on in a separate page. If you want to participate and give feedback on the design please go to the [[Samples_Index_File_Specification]] page.
  
Sample clients need to be able to consume information on samples in order to provide this functionality. Sample index file need to contain a section dedicated to sample metadata.
+
* Post specification finalization a method of accessing the samples needs to be established. For M1 this is expected to only be in the form of a ''simple'' client used to read a cache of sample index files and display the results. Simple in the respect that is does not provide any connectivity or synchronization with a central repository of samples. It should at least provide rudimentary display, categorization and search capabilities allowing users to narrow down what kind of samples they are actually looking for.
  
* Name: Sample name/title
+
== Milestone 2 ==
* Synopsis: Brief description of the sample
+
* Description: Full description and any information a user will need to know
+
* Product: EiffelStudio | EiffelEnvision | Eiffel for ASP .NET | Other
+
* Product Version: 5.7 | 6.0 | ...
+
* Technology: Language, Eiffel for .NET, EiffelBase, ...
+
*
+
  
 +
The second milestone should add a central download repository. A central server to download, upload and search samples from.
  
 +
=== What Needs to be Done ===
  
 +
* Establish a central repository for samples and develop a means of download and uploading samples. This is not to be specific logic geared towards web pages. It may be a simplistic protocol or web service that can be used by disparate clients Web, GUI or otherwise.
  
= Examples Sites =
+
* Create the start of a community website where users can download, upload and search the sample repository.
  
There are parties out in the Eiffel community that are trying a single effort to rectify this but that leads to another problem - consolation. Sites such as [http://www.codeproject.com Code Project] and [http://nehe.gamedev.net NeHe] are good examples of consoladation and ease of access to samples and walkthrough.
+
* Add connectivity and synchronization to the client application developed for M1.
  
CodeProject supports a community and supplies users
+
==== Examples Sites ====
  
 +
There are parties out in the Eiffel community that are trying a single effort to rectify this but that leads to another problem - consolation. Sites such as [http://www.codeproject.com Code Project] and [http://nehe.gamedev.net NeHe] are good examples of consolidation and ease of access to samples and walkthroughs.
  
There are a limited number of tutorials
+
== Milestone 3 ==
  
= A Central Repository for Samples =
+
The third milestone concerns itself with integration.
If Eiffel Software or ETH were to host a Eiffel community site an RSS/ATOM feed could be offered. The metadata and description in each sample could be extracted and added to the feed when update. Samples that are update would also be added to the feed but with little information, more of a notification.
+
 
 +
=== What Needs to be Done ===
 +
* Integrate the client tool inside of EiffelStudio to provide direct access to samples, loading and compiling them.
 +
* Create a walkthrough system to integrate into EiffelStudio showing step by step instructions on building a project that the user can follow at their own pace.
 +
 
 +
== Other Things to Think About ==
 +
 
 +
For any other subjects related to a sample browse, place under this category.
 +
 
 +
=== Providing Web Access Library ===
 +
The business logic for clients to access samples from a live repository should be provided in a reusable Eiffel library so the OS community can build their own clients.
 +
 
 +
=== Syndication Feeds ===
 +
If Eiffel Software or ETH were to host a Eiffel community site an [http://en.wikipedia.org/wiki/RSS_%28file_format%29 RSS]/[http://en.wikipedia.org/wiki/ATOM ATOM] feed could be offered. The metadata and description in each sample could be extracted and added to the feed when update. Samples that are update would also be added to the feed but with little information, more of a notification.
  
 
There could actually be multiple feeds for those interested in a particular technology. A feed for Eiffel for .NET, Linux samples, ... or whatever the community is calling out for.
 
There could actually be multiple feeds for those interested in a particular technology. A feed for Eiffel for .NET, Linux samples, ... or whatever the community is calling out for.
  
= You chance to participate =
+
=== A Sample Authoring Tool ===
We've made this page public so the Open Source community can participate in the development of a samples and walkthrough platform. Our strategy is to not only maintain samples and walkthroughs ourselves but to have the community post samples, walkthroughs and articles also. Any feedback on our strategy, how to better distribution, things you like or don't like, let us know.
+
It would be nice to have a tool for creating the sample index files. This is not in any milestone because the sample index files should be human readable and writable. A authoring tool could also integrate uploading samples to the repository.
 +
 
 +
The upload logic should also be contained within a library for client reuse.
 +
 
 +
=== Code Monkey See Code Monkey Do ===
 +
 
 +
For future development it would be fantastic to integrate a walkthough mechanism into EiffelStudio. A mechanism by which the user watches a series of steps being performed for them upon request. Such functionality could be tied in with the GUI testing framework under research here - [[GUI_Testing/Framework]].
 +
 
 +
Lego Mindstorms graphical editor provides this functionality and have a web sample on line [http://www.ni.com/academic/mindstorms/works.htm here] (Click Test Drive image.)
 +
 
 +
=== Extending ECF ===
 +
 
 +
As an extension, the new ECF format could be extended to reference sample URLs for instance access to associated samples on how to use the library. This way all library vendors can automatically associate samples with their library and Eiffel IDEs can provide access to those samples.
  
= Development Roadmap =
+
= Your chance to participate =
* Create and finalize a proprietary sample specification using XML for use by client applications, web tools and other tools to offer content synchronization.
+
We've made this page public so the Open Source community can participate in the development of a samples and walkthrough platform. Our strategy is to not only maintain samples and walkthroughs ourselves but to have the community post samples, walkthroughs and articles also. Any feedback on our strategy, how to better distribute and provide examples, things you like or don't like, let us know.
* Add a community web site where samples can be downloaded or uploaded to.
+
* Offer feeds from web site.
+
* Develop a client application to use as a stand-alone that synchronizes with web content and provides the ability to download and refresh samples.
+
* Integrate client application into EiffelStudio.
+
* Extend community web site to allow authoring of articles related to Eiffel.
+

Latest revision as of 11:07, 30 May 2007

Overview

This page is dedicated to discussing the evaluation of Samples and WalkThrough project.

The project is designed to increase exposure of Eiffel in a multi-facet manner with both the expertise of in-house Eiffel Software developers and employee as well as the Eiffel community. The samples will express everything for new syntax being released, show casing library/language research, help new users get to grips with Eiffel for the first time and help those already using Eiffel to take advantage of advanced concepts.

With a strong community affiliation samples will appear showing off Eiffel in domains Eiffel Software themselves have not conceived or using Eiffel in novel ways, as well as showing off Eiffel tips, tricks and practices to avoid.

The Problem

Samples are not being produced at a rate to match changes in the Eiffel language so users outside of Eiffel Software are not always aware of new features or tips and tricks that make Eiffel a fantastic language platform. On the road map to ECMA compliance there are going to be a number of language additions that benefit all. Users are left with outdated or archaic samples to base their projects on. Their use of Eiffel is marred instead of enriched.

Getting started with Eiffel is harder than it should be; there are small number of samples and tutorials dedicated to getting started with Eiffel, introducing the language and it's constructs. There are little walkthroughs to begin writing a first program using EiffelStudio and no samples for advanced concepts. As of today most samples and walkthroughs are attached to a Eiffel library and some libraries do not even have provided examples, forcing users to become hackers of sorts by reading the library source code in order to figure out how to use it.

This needs to change!

Proposition

What is being proposed is that Eiffel Software provides a means to access samples, where it be through a client application (a stand-alone or through EiffelStudio) or via a web interfaces. In order for tools to be developed to support sample browsing, every sample should be attached to a description containing informative text and metadata for consumption by client tools.

Project Roadmap

Below is the tentative roadmap for development. Each milestone represents a way point of completed development. Depending on time and resource each milestone will indicate a release.

Milestone 1

The first milestone is dedicate to creating the first version of a sample browser tool for use with a downloaded version of a Eiffel Software product.

What Needs to be Done

  • Before beginning any specification or design for any client tools a specification needs to be drawn up for a sample index file. This specification is being worked on in a separate page. If you want to participate and give feedback on the design please go to the Samples_Index_File_Specification page.
  • Post specification finalization a method of accessing the samples needs to be established. For M1 this is expected to only be in the form of a simple client used to read a cache of sample index files and display the results. Simple in the respect that is does not provide any connectivity or synchronization with a central repository of samples. It should at least provide rudimentary display, categorization and search capabilities allowing users to narrow down what kind of samples they are actually looking for.

Milestone 2

The second milestone should add a central download repository. A central server to download, upload and search samples from.

What Needs to be Done

  • Establish a central repository for samples and develop a means of download and uploading samples. This is not to be specific logic geared towards web pages. It may be a simplistic protocol or web service that can be used by disparate clients Web, GUI or otherwise.
  • Create the start of a community website where users can download, upload and search the sample repository.
  • Add connectivity and synchronization to the client application developed for M1.

Examples Sites

There are parties out in the Eiffel community that are trying a single effort to rectify this but that leads to another problem - consolation. Sites such as Code Project and NeHe are good examples of consolidation and ease of access to samples and walkthroughs.

Milestone 3

The third milestone concerns itself with integration.

What Needs to be Done

  • Integrate the client tool inside of EiffelStudio to provide direct access to samples, loading and compiling them.
  • Create a walkthrough system to integrate into EiffelStudio showing step by step instructions on building a project that the user can follow at their own pace.

Other Things to Think About

For any other subjects related to a sample browse, place under this category.

Providing Web Access Library

The business logic for clients to access samples from a live repository should be provided in a reusable Eiffel library so the OS community can build their own clients.

Syndication Feeds

If Eiffel Software or ETH were to host a Eiffel community site an RSS/ATOM feed could be offered. The metadata and description in each sample could be extracted and added to the feed when update. Samples that are update would also be added to the feed but with little information, more of a notification.

There could actually be multiple feeds for those interested in a particular technology. A feed for Eiffel for .NET, Linux samples, ... or whatever the community is calling out for.

A Sample Authoring Tool

It would be nice to have a tool for creating the sample index files. This is not in any milestone because the sample index files should be human readable and writable. A authoring tool could also integrate uploading samples to the repository.

The upload logic should also be contained within a library for client reuse.

Code Monkey See Code Monkey Do

For future development it would be fantastic to integrate a walkthough mechanism into EiffelStudio. A mechanism by which the user watches a series of steps being performed for them upon request. Such functionality could be tied in with the GUI testing framework under research here - GUI_Testing/Framework.

Lego Mindstorms graphical editor provides this functionality and have a web sample on line here (Click Test Drive image.)

Extending ECF

As an extension, the new ECF format could be extended to reference sample URLs for instance access to associated samples on how to use the library. This way all library vendors can automatically associate samples with their library and Eiffel IDEs can provide access to those samples.

Your chance to participate

We've made this page public so the Open Source community can participate in the development of a samples and walkthrough platform. Our strategy is to not only maintain samples and walkthroughs ourselves but to have the community post samples, walkthroughs and articles also. Any feedback on our strategy, how to better distribute and provide examples, things you like or don't like, let us know.