Brent, Stefan, and Chris met with Christina to discuss current work and the plan for the final weeks.

  • Christina asked for opinions on how successful the course was so far.  We agreed that when viewed in isolation, our end product is not as substantial as might be expected, but it represents a lot of work.  This work included various successes and failures that were required to arrive at a suitable template, and the extensive communications that were necessary to establish concrete requirements and understand the topics.
  • We spoke about our current writing.  Christina offered a writing improvements, but expressed overall satisfaction.  We agreed each page should have some sort of relevant diagram/picture.
  • We outlined our timeline of events for the last two weeks of the course:
    • On Wednesday the 31st, meet with Boris and discuss a third service
    • On Monday the 5th, send candidate final documentation to Eclipse team
    • On Wednesday the 7th, meet with Eclipse team to discuss product and get feedback
    • On Friday the 9th, present final product (with any modification from feedback) at class meeting

March 12 Meeting Minutes

March 13, 2010

Attendees: Brent, Chris, Stefan, Boris

We had a very helpful meeting with Boris regarding User Preferences where we were able to gather all or most of the information we need.

– Pair writing to turn the conversation into a piece of documentation on Monday March 15

– Stefan will try to book a meeting with Susan for Wednesday at 230 PST (430 CST)

– Pair writing for the service we talk to Susan about on Friday at 2:30

Feb 26 Meeting Minutes

March 1, 2010

Attendees:

Stefan Dimitrov, Brent Barkman, Chris Hildebrand, Christina Penner

Discussed web site

  • like new format
  • minutes are good
  • informal nature is comfortable

Commented on last meeting being valuable

  • how has this driven our progress up to today?
  • Stefan contacted Susan Franklin re: one of his services, will contact Boris about other one
  • No other contact with Eclipse people, no writing of actual documentation
  • Christina: You are running out of time!
  • no format or content

Approaches

  • Brent suggested a subset of headings from the GoF book
  • Chris suggested a case study that incorporates a several (or all) services
  • Chris suggested a glossary (either global) or at the page level
  • Stefan commented on the use of more diagrams – kind of on the back-burner
  • Chris commented that perhaps we can’t follow a set-in-stone template
  • Brent: but templates are great for readers
  • Like trying on clothes: wait and see

Timelines and deadlines

  • How are we going to get this done on time?
  • Chris: the Eclipse people need to drive the conversation
  • Maybe pair writing for the entire project?
  • OK. (Analogy to going to the gym/yoga).
  • Plan: Set up 3 meetings – one per project.
  • two 20-minute meetings per person, per service – meetings should be set up by next meeting.
  • How are we going to present something on wednesday?
  • get an evolved template
  • get as much content as we can
  • also, can talk about communications challenges?
  • also, bring the blog into the conversation (change in medium brought change in attitude)
  • mention the comparison of this project to agile software development
  • Deliverable: working template, content may be “old and minimal”

Aside: Can we have final class meeting on April 9th? Yes, at 14:20 .

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.

Learning from the Pros(e)

February 26, 2010

When approaching any difficult problem, it is often helpful to examine the solutions to other, similar problems.  Writing documentation is no exception.  So, when presented with the task of documenting a set of application services in a development framework, it would seem reasonable to consult the documentation of similar products.

“Design Patterns”

One piece of documentation which has become a recurring topic of discussion at our team meetings is the much-lauded gang-of-four “Design Patterns” book.  Its value in relation to our task has already been discussed by Brent here.

Microsoft’s .NET

Microsoft’s .NET framework is both mature and corporately-sponsored.  As such, good documentation would be expected.  Of course, documenting the .NET framework in its entirety is a much larger task than documenting application services in e4.  A sub-area of .NET which is at least somewhat analogous, however, is .NET’s Windows Communication Foundation (WCF).

The WFC still contains a lot of documentation, but there are two sub-sections that I find particularly relevant: the Conceptual Overview and the various Feature Details.

The obvious mapping of .NET’s conceptual overview is to an overview of the e4 service model, which is likely something that would not be done by our team.  Given the conceptual approach that we are taking to documenting individual services, though, there are several ideas which could be relevant.

  • The document What is the Windows Communication Foundation contains 3 essential sub-sections:
    • An high-level description of what WCF is/why it exists
    • A concrete problem (car reservation app) that the WCF can be used to solve
    • A summary and subsequent breakdown of how WCF features/principals solve the example problem

    All of this is done in a code-agnostic way. I think the idea of presenting a concrete
    problem and demonstrating how it is solved by the tool (service) at hand would work well in the context of e4 application services.

  • In Fundamental Windows Communication Foundation Concepts, a list of relevant terms and their definitions is provided.  Again, their is no code, save a few references to the names of Classes which define the terms.  I think this would be useful to our service descriptions.  (E.g. If I am describing the Saveable Life Cycle, the reader needs to know something about SaveableParts and a Viewparts).

The documentation of WCF’s features seems like it should be relevant to our project because it describes a set of closely related framework provisions.  After taking a closer look at the documentation for several of these features, there are two things that are worth noting:

  • There isn’t a generalized format for documenting each feature.  In fact, while some features are only allotted a single page, others span many pages and sub-sections.  Even between sections that one would expect to be congruent, such as the “Overview” sections of two features, there is significant variation.  I haven’t formed an opinion on whether this is a good approach, but perhaps an imposed structure is too restrictive.
  • In spite of its lack of a consistent structure, the documentation of WCF’s contains very little code.  If we find that writing code-agnostic documentation is challenging, this documentation could be consulted for further insight.  It is important to note, however, that code is not completely absent.  This description of WCF’s data transfer architecture, for example, still includes non-negligible amounts of code.

Finally, I stumbled upon a pretty cool diagram while surfing the .NET:

.NET Framework Diagram - source

I thought that this type of diagram could be a great way to visually represent the relationship of services to one another, and to Eclipse’s underlying framework.  The core of the circle could represent the framework’s inner workings, with services closer to the outside.  Radial proximity could be used to represent group similar services, and layering of various services could show the dependence of services upon other services.

With my limited knowledge of the e4 service model and how services are related, I’m not sure how well this would work, but it seems like something that is worth mentioning.

“Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications”

This book is the definitive guide to Eclipse RCP, and so I thought there was a good chance it would have something to teach us.  Although my examination of its documentation practices was brief, I found its use of an ongoing example to be interesting.

I have already noted the use of example problems in documentation, as is done in .NET’s conceptual overview. The Eclipse RCP book’s use of a single problem to highlight the usefulness of multiple concepts builds upon this idea.  Throughout the book, an instant messaging application is built using the recently discussed tools.  Code snippets are given inline, and the complete source code is provided electronically so that the reader can install and run various iterations of the program as its development progresses.

Certainly, our project doesn’t warrant a coded example.  I do, however, think that the periodic mention of a hypothetical application that incorporates many/all services could be useful.  In addition to demonstrating how each service is useful, it would provide cohesion among our descriptions and potential provide insight into how services are related.

Summary

So, to recap the relevant documentation techniques that I have observed:

  • From Microsoft’s .NET (esp WCF)
    • Providing a relevant problem and describing how the topic at hand is a solution
    • Providing a list of relevant terms and definitions (essentially an in-page glossary)
    • Avoiding a concrete template so that the content can dictate the format (form fits function?)
    • Using code snippets sparingly, but not abolishing them altogether
    • Using a cool circular diagram to depict layered services in a framework
  • From the Eclipse RCP book
    • Using a single concrete example across all services

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.

The GoF book uses a consistent structure for documenting each of their services and as we have discussed repeatedly now on the applicability of their model to ours, I’ve taken a look at their structure and will outline my thoughts on each of their sections. I will list out the section and my thoughts on it’s applicability to our project:

Intent

A brief (1 sentence) description of what the pattern does. e.g. “Provide an interface for creating families of related or dependent objects without

specifying their concrete classes.” I like this as it’s quick, doesn’t require a lot of effort, let’s you quickly get an understanding of what it does and I think can be used in our model.

Also Known As

I don’t think we really need this.

Motivation

This section speaks to why the pattern is useful and to what problem it solves, really why it exists in the first place. This is an excellent candidate for our services which may not be obvious for some of the less generic ones and gives excellent context to learning about what it actually does. It’s slightly longer than the others (2 – 3 paragraphs) which I think would be an appropriate goal length for ours as well.

Applicability

The book uses this section to give a quick (bulleted) list of some situations when to use this pattern. Another excellent candidate for our services, a quick list to highlight some scenarios when you’d want to use a particular service.

Structure

A (graphical) representation of what the pattern looks like, UML diagrams. I don’t think this is overly helpful to our cause the “structure” of the service I don’t feel is particularly important to how it’s used or implemented. Really the implementation details will figure out the structure as need be but there is not necessarily a common one. A simple example is Loggers which can be implemented in and have drastically different structures depending on the targeted output.

Participants

This section of the book details the participants as show in the structure; if we don’t need a structure section we don’t need this either.

Collaborations

Who does what; again not needed for our format.

Consequences

This section talks about the benefits and liabilities of using each pattern. I don’t have a definite answer but I don’t know that this would be that helpful for talking about the risks and rewards in using a specific service. There may not even be another way in some cases, which is where we differ in concept from the book in that they are taking a collection of practices that are a bit of the “wild west” in how they are done and attempting to pull out the good parts and standardize them into patterns whereas a lot of our services are simply THE way you do something.

Implementation

This section is a little closer to the metal and gives hints and considerations when implementing the pattern. It will do things like highlight languages, language constructs or features etc. that suit a particular pattern well and provide some issues to think about in the implementation. Something akin to this would be useful as a brief section in the details on the producer of a service, some things to consider when implementing it that the developer may not have thought of otherwise.

Sample Code

Self explanatory and as previously discussed we are trying to avoid discussing the services at this level.

Known Issues

<insert any 1 of many jokes about the current state of the code/documentation here> This section talks about certain implementations of the services in different software packages and some known issues regarding them. Not applicable for us.

Related Patterns

Related services would certainly be applicable… “People using this service have also bought services X, Y and Z” a’la Amazon.

In summary, the sections I think we can borrow (copy) are:

  1. Intent
  2. Motivation
  3. Applicability
  4. Implementation
  5. Related Patterns (Services)

To give it the 5 W’s test, we have the Who and the When in Applicability, we have the  Why between Intent and Motivation. The What is sort of implied in Intent and Motivation but perhaps we should still include a description of exactly what the service is? The Where is missing completely, and we should include a Usage section perhaps on how to use it, not from a code level but more abstractly, like to say “query the context for it” etc. The Related Patterns (Services) section provides some good further information, but looking at some of the sections we skipped from the book, I would think it may also be useful to add a section called something like Tips or Extra Info to have a spot to put any other tidbits of information that would be useful. The book formalized them into their own sections because they had enough of it for each pattern, but in our case I think we may just have some tidbits here and there and it would be more consistent just to have a little section to put them in.

This post was just an initial flyby of the style used in the book, the real test on applicability will be trying to fill the sections we’ve thought of to see how it really fits. This is a perfect example of an article of clothing looking like it’ll fit in the store and being 3 sizes to small when you bring it home; you just don’t know until you try it on.