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.

Coming out of the woods…

February 15, 2010

In our Feb. 12 meeting, I think there was a lot of clarity found regarding how the project should move forward. Prior to this, we were all feeling a little bit lost in how to go about completing the project. It seemed awfully daunting to have to get 20 or so templates done without even having a clear idea on how to do them, especially with the end of the term approaching so quickly.

In the meeting I think we really hammered out what the deliverables on the projects were going to be and set some realistic expectations for ourselves. With extremely helpful input from McQ and Boris we started by attacking the problem of exactly how to go about documenting these services in such a way that was language agnostic. We had come up with a template and an idea of what we thought this would look like before-hand, however after some good discussion and gentle urging from McQ we have modified it a bit. Rather than the general approach of reaching out to the community for feedback we are going to approach the people working on each specific service directly. In documenting each service we are going to follow a model more closely related to the famous GoF design patterns book as they faced a very similar problem of documenting without talking about a specific programming language.

This was a perfect segway into a broader challenge we are facing in this project. The task of documenting a moving target (e4 is changing everyday, the source code you look at to figure out how something works one day may be completely different from what it looks like a week later) and doing so in a distributed manner (the Eclipse foundation is spread out over many people from many different countries).

We feel that a more direct approach to specific people will solve both of these problems for us. We are prime candidates for writing this documentation, we have relatively little knowledge of the Eclipse platform (compared to the general software developer we probably have above average knowledge, but compared to an eclipse plug-in developer we’re way below….). If we document and track the questions we have regarding how particular services work prior to talking to the people working on them, document the conversation we have with them doing our best to answer all of our questions and glean any additional and relevant information that we can and then put it into a form that works (assuming something akin to the GoF style), we think we will have a successful project. This gives us clear and most importantly actionable goals and really serves the purpose of the documentation: provide the answers to questions someone who is new to the e4 platform is going to have when they start developing on it. The conversations are not likely to center around code samples but rather a general understanding of how the service works, which gives us the perfect level of abstraction to write about the service and stay away from a big page full of code.

As this project has unfolded itself, we have seen there are many challenges we did not anticipate early and as is always the case, there are likely more to come. However I feel this is coming together to form a clear understanding of what this project really is and while we are not going to have a large number of the services completed by the end of the term, the process of doing a couple each will let us really refine what the final form should look like and iron out any wrinkles so that in the future someone can very easily pick-up where we left off.

*** Posted on our no longer used Google Site on Jan 29 by Brent ***

How do you communicate when you don’t know what you’re communicating? How do you teach people something you don’t know yourself? How do you teach SMART people something you don’t know yourself? Interesting questions, easy to ask, not so easy to answer. This project will be the exploration and tangelization (I always thought that if I ever started blogging I’d do my best to make up a new word each post) of that problem. I wonder if there are patterns for this like there are patterns for software design. Perhaps I should email Erich Gamma and the rest of the “Gang” and ask them for some patterns? That is an interesting thought actually and perhaps one worth looking into: the existence of communication patterns.

In any event, it does little to solve the problem at hand. There is no clear solution but the proposed answer is in fact to not answer the question but rather let someone else do it. This would appear at first glance to be the “students manifesto” as it were but a slightly deeper analysis might reveal it to be something that can actually work. If you look at the facts:

1) We don’t know the right way to do it, nor do we have any experience
2) We KNOW we don’t know the answer, which is a pretty big realization…
3) We DO know the people who have the answers, but they are a diverse crowd

So we may be able to solve a different problem and in turn solve our original: stimulate, organize, motivate and perhaps even coerce the people with the answers to bestow on us the knowledge and information we need to communicate to the world. Our new problem is knowledge aggregation and this one is much more solvable. So, the plan…..

1) Discover what we do and don’t know about each topic we need to communicate
2) Present our findings in an easily accessible, familiar way with easy feedback mechanisms
3) Solicit (in the positive sense, as in most cases it will be self-serving for our solicitees, hey look TWO new words, provided you’re not referencing a legal dictionary…) feedback
4) Analyze organize
5) Wash, rinse and repeat

Sounds a little bit like agile software development eh? Maybe this idea of communication patterns has some merit after all!