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.

About these ads

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: