Samples and Walkthroughs
- 1 Overview
- 2 The Problem
- 3 Proposition
- 4 Project Roadmap
- 4.1 Milestone 1
- 4.2 Milestone 2
- 4.3 Milestone 3
- 4.4 Other Things to Think About
- 5 Your chance to participate
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.
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!
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.
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.
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.
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.
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.
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.
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.)
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.