A Fusion Of Formats

March 1, 2010

An important part of every text is its format. As we discovered while working on this project, the right type of format is particularly important when documenting computer products. We first started by looking at a Wiki and recreating it with our own “improved” template. Before gaining insight into the actual content, we tried to devise a structural organization that we would expect to see in a document of this type.

Our Template

We were planning on including the following categories:

1. Description

2. Consumer

2.1. Usage

2.2. Code Samples

2.3. Eclipse 3.x

3. Producer

3.1. Usage

3.2. Code Samples

3.3. Eclipse 3.x

4. Related Materials

4.1. Related Services

4.2. Related API’s

4.3. See Also

Clearly our focus was on including as much relevant content as we could. However, as we started familiarizing ourselves with the core services and their usage, a number of questions arose. Do we have information for all of the categories? Are these the kind of categories a new developer would expect to see? How would our documentation be different from the Wiki that already exists?

Looking for an answer we decided to review the Design Patterns book, a well known authority for modern software developers. There certainly are similarities between the design patterns in Object Oriented programming and the core services in Eclipse. The most obvious example would be that both the GoF and our team are trying to present a general approach, instead of a detailed code implementation. Nevertheless, with Design Patterns the focus appears to be on their structure and development while for the core services we would like to document the features, relationships and applicability. Therefore, some of the categories that appear for each one of the Design Patters are not necessarily relevant to our format. A short list of the ones that we could use was compiled by Brent.

The Design Patterns

1. Intent

2. Motivation

3. Applicability

4. Implementation

5. Related Patterns

Most of the items from this list were already present in our initial template, but organized differently. Perhaps, the authors of the Design Patters book found good reasons to use these categories. We can certainly learn from their experience and transform our template into a closer resemblance of the aforementioned categories. The idea will improve our document by contributing the Intent and Motivation paragraphs which were overlooked to some extent in our template. However, from working on the e4 core services we know that there still remain pieces of information which we have to fit in the document. May be this is a good place to borrow from the legend in computer software: Microsoft. Chris reviewed the .NET documentation which has couped in many aspects with issues similar to the ones we are encountering. For instance, an example can sometimes be worth million words. The example can be in the form of a case study, a snipped of code or a list of relevant terms. Anything that helps demonstrate the power and flexibility of the services would be helpful.

.NET

1. Case Study

2. Relevant Terms

3. Code examples

4. Diagram

5. Flexible template

The above list of contributions can add “the missing piece” to our format and help us create a new template which encompasses most of the relevant categories for our documentation. It will likely continue to evolve as we continue working on the project but it can make for a good starting point for our discussions.

Revised Template

1. Description (+Intent)

2. Relevant Terms

3. Motivation: Case Study

4. Applicability and Usage

5. Implementation

5.1. Code Examples

6. Related Services

7. Diagram

We may also retain the ability to skip certain sections if necessary, providing for a flexible template. By mixing our own experience and expectations, together with the experience of the renown Design Patterns experts as well as the .NET documenters and, last but not least, with the valuable contributions from the Eclipse development team and our professor Christina Penner, we are on our way to creating a better and more useful documentation.

Advertisements

A different perspective…

February 23, 2010

Little did I know about the essence of this project when I joined the team. I had both academic and industrial experience with Eclipse, but I had never developed my own plug-ins. As the project progresses and I work on the services, I am gaining better understanding of the powerful Eclipse RCP features that have paved its way to a leading IDE.

At University of Manitoba most of us have used Eclipse at least for Java programming. I have also used it for C++ and for BlackBerry Java development. However, this is just one of “the faces” that the platform has to offer. Developers can build on the flexible components, core services and UI to implement their own platforms suited for various specialized environments such as Bioinformatics, BlackBerry application development, microcontroller programming, etc.

Brent and Chris seem to have had hands on experience with this “other face” of the Eclipse platform. This is certainly helpful for the understanding and documenting of the core services. On the other hand, I am approaching this project as a “prospective developer”. Thus, when documenting the services and relations between them at a high level, I can focus on the generic and language-independent concepts. In my view, this is close to the goal of the project.