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.


Leave a Reply

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

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

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s

%d bloggers like this: