Difference between revisions of "E4/Doc/ProjectDetails"

Revision as of 10:23, 8 April 2010

Project Specification

Project Goals & Definition

The goal of this project is two-fold: Unearth and refine a process for creating Eclipse 4 Core Application Services documentation and with a process in place, document as many of the services as possible.

The development of the documentation is a collaborative effort between a team of computer science students at the University of Manitoba and the wider Eclipse community.

The project is part of a fourth year technical communications course in the Computer Science program at the U of M and runs from January to April of 2010.

Medium

Development of the documentation occurs on this wiki. Upon finalization, the wiki pages will likely be converted into the Eclipse Help format.

A list of existing wiki pages is kept here. The documentation for each application service resides in its own page and conforms to this template.

Process

Due to our (the students) limited existing knowledge of the platform as well as relatively short time constraints, it would be unfeasible to assume we could be the single source/aggregator of all relevant and applicable knowledge relating to the services. Instead, we go right to the source and interview the developers of the service. We have (phone) meetings and essentially are "taught" what the services do and how they work. We then individually and collaboratively take the knowledge gained in the interview and turn it into documentation on this wiki.

We believe this to be an effective process as it highlights and solves the key problem we are trying to solve. Like the future readers of our documentation, we know little about each of these services or at least how they are done in E4. By having the developer of the service teach us, we then ideally have gotten all of the pertinent information that we needed to learn the service and conveyed it accurately and concisely in the documentation.

Collaborators

• IBM Eclipse Developers
  • Mike "McQ" Wilson
  • Boris Bokowski
  • John Arthorne
  • Susan Franklin McCourt

• A team of University of Manitoba students and their prof
  • Prof. Christina Penner
  • Brent Barkman
  • Stefan Dimitrov
  • Chris Hildebrand

In Retrospect: Lessons Learned

Writing technical documentation for unreleased software presents a formidable challenge, particularly when undertaken for the first time. An evolving product presents a moving target for documenters, who must keep apace of continous change. When writing about previously undocumented software, a common framework must be established, and information must be gathered directly from the people who possess it.

During our semester-long experience of documenting Eclipse e4, we encountered each one of these difficulties. With our delivery of a reusable template and several documented services, we have also identified a number of lessons which will be valuable to those who come after us.

Identify Project Goal

One of the most important aspects of a successful project is a unifying goal. Although many project requirements must be defined as a project evolves, a high-level goal provides a measure against which progress can be measured.

In our first meeting with the Eclipse team, we were told to write documentation that focuses on the high-level, code-independent design of e4's services. This goal became a recurring topic of our team discussions as we evaluated how our efforts worked toward its accomplishment.

Establish A Template

We found it necessary to establish a template early in the documentation process. Our template was a useful guide for both information gathering and writing. While interviewing Eclipse developers about application services, our template helped us formulate questions that would yield suitable information for our writing. Our template was also a crucial component of writing documenation, as it enforced consistent formating and provided a framework for organizing our ideas.

Developing a suitable template was a challenging task, and our first attempt was unsuccessful. A good template must be suitably restrictive; a template needs to be general enough to apply to a range of topics while still enforcing consistency and providing useful guidance. To arrive at our final template, we consulted a variety of existing professional documentation, and adopted practices which suited our project. We found the legendary Design Patterns book (authored by the "Gang of Four) to be a particularly useful model for documenting software conceptually.

Define the Learning Process

Because our project involved documenting software which we did not develop, learning about our subject matter required a sizable portion of our effort. When we first approached the subject of information collection, we decided to passively solicit information from the Eclipse community (using mailing lists, wiki pages, etc). We quickly realized that this approach would not work. A broadcast-style request is not only ineffective in garnering responses, but also proves inadequate when very specific information is required.

Having identified the problems with our approach, we decided that it was instead necessary to gather information about e4's services from those who were most familiar with them.

Non-Code Contributions

This was one of if not the first time the Eclipse foundation has received community contributions that are not code based. We hope that our experiences are able to serve as a guide for others looking to contribute in similar fashion in the future (perhaps to finish what we started!) and hopefully to encourage some "softer" contributions to the Eclipse Foundation as well. To put it simply: we have shown it can be done!