After our Feb 12th meeting with the Boris an McQ, there was unanimous agreement among our team members that we had finally reached a suitable project plan.  The scope of our project had been narrowed from a daunting 20+ services to a much more manageable “several”.  Our primary source of optimism was not the promise of less work, though.  Instead, our optimism resulted from a shift in the type of work we would now endeavour to complete.

Our initial plan of documenting twenty-odd services was quick to demonstrate the deficiency of our Eclipse knowledge.  After creating a basic service template and using it to create initial documentation for a handful of services, Stefan and I reluctantly asked a painful question:  “How is our work different from the (pretty mediocre) documentation which already exists on the e4 wiki?”

Of course, the answer to this question is that it’s not…yet.  Until our last meeting, we had expected to solicit widespread community contributions to fill out our documentation and compensate for our lack of e4 expertise.  In this way, we were to produce in-depth documentation without ever needing in-depth knowledge of what we were documenting.  But our meeting forced us to confront a problem with this plan:  In spite of being engaged and knowledgeable, the Eclipse community would need more than our passive requests to involve itself with our project.

With neither adequate knowledge nor a method to easily obtain it, it was clear that we needed a new game plan.  During our Feb 12 meeting, it quickly became clear that this plan would include a narrowed scope and greater focus on documentation design.  That is, from the diametrically opposed properties of quantity and quality, we had chosen the latter.

Producing high quality documentation for a small number of services solves our knowledge problems on two counts.  First, the narrowed scope allows us to devote more of our limited time to learning about each service.  Instead of shotgun approach to information collection, we can actively (aggressively?) solicit one-on-one communication with developers who know about the services we are interested in.  Second, an increased focus on format allows as to divert some of our efforts from information collection to knowledge creation.  In this way, our final deliverable will not be evaluated solely on the completeness of its information.  Instead, the quality of the method by which  we convey information will equally represent value to the Eclipse team.

Advertisements

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.

Feb 12 Meeting Minutes

February 14, 2010

Attendees:

Stefan Dimitrov, Brent Barkman, Chris Hildebrand, Christina Penner, McQ (Mike Wilson), Boris Bokowski

Brent updated McQ and Boris on our current plan

  • We have a template (on wiki)
  • We have a skeleton of several services (on wiki)
  • We now plan to reach out to Eclipse community for help & wiki contributions

We discussed the best way to solicit community involvement

  • concluded that passive communication was probably not going to work.
  • instead, we need to aggressively contact individuals that we know are personally involved in a given service
  • Challenge:  Document something that is continuously changing, and where information is distributed between many people

We discussed our current template

  • concluded that we are focusing too much on usage, not “big picture” aspects of e4
  • McQ commented that he would like to have pages that describe general e4 principles and relationships between services
  • Brent suggested that we have a graphical representation (possibly with physical metaphors) that relates services to one another
  • McQ also noted that our template should better describe it’s own sections, indicated what information goes in each place
  • Boris gave wiki.eclipse.org/EGit as an example for navigation (categorized tabs and tabular links)

We discussed our overall project goal

  • McQ poignantly stated that it will be better to do an excellent job with a few services than a mediocre job with all of them.
  • Boris gave the Design Patterns book (Gang of Four) as an example for the type of documentation we are striving for
  • We are trying to explain the design of services instead of just providing code for how to use them

*** Boris and McQ left meeting ***

We discussed the idea of logging personal experiences throughout our documentation process

  • Given the somewhat nebulous task at hand, Christina pointed out that a record of our progress could prove valuable
  • Agreed to use an informal blog to track project progress

We (Stefan, Chris, Brent and Christina) decided to meet next on Feb 26th

Service Template

February 12, 2010

*** Posted on our no longer used Google site on Feb 4 by Brent ***

The service template formatting is complete and can be found at “http://wiki.eclipse.org/e4/Doc/Template”. The structure isn’t set in stone so if it makes sense we can consider evolving it further.

Jan 29 Meeting Minutes

February 12, 2010

*** Posted on our no longer used Google site on Feb 1 by Chris ***

Following is a summary of our meeting:

– We received everyone’s progress.
– Chris suggested a template similar to a Wiki which was adopted for the documentation.
– I had reviewed my topic and brought up the issue with access to the Eclipse source code. I had also summarized my topic, but in a format that was considered inferior to a Wiki.
– Brent had reviewed his topic, provided information about accessing the source code as well as Eclipse’s proprietary documentation format and its specifics (XML and CSS).
– Chris’ format of a Wiki appears to be closest to the Eclipse documentation format and was unanimously adopted as the format of the Eclipse 4 services documentation.
– We decided to use the Eclipse website as a “sandbox” environment for our documentation. Brent took on the responsibility to contact the Eclipse team about gaining access to this platform. Chris agreed to search for and try to post a link.
– Brent agreed to write the “Under construction” template box which will be applied to all pages within the project.
– Chris agreed to write an “About Page” which will describe our effort and goals with regards to this project as well as provide contact information for the Eclipse community.
– We decided to focus on writing the core documentation for the 20 Eclipse 4 services, while relying to certain extent on the developer and user communities for suggestions, corrections and general feedback.
– The generally agreed on meeting time for “small meetings” involving Stefan, Brent and Chris was tentatively scheduled to be Monday from 2:30pm.

Documentation Template

February 12, 2010

*** Posted on our no longer used Google site on Jan 30 by Chris ***

In our Jan-29 meeting, we decided upon a documentation format which includes, for each service:

1. A basic description of what function the service performs or why it exists. Information this section is not expected to be specific to e4.

2. An “In Eclipse e4” section which describes how the service is approached in e4. It can include a design description, necessary definitions, important considerations. This is also the place where relationships to other services will be noted. This section should remain code-agnostic.

3. A “Usage” section which gives code examples for how to use the service.

Attached is a sample of what such document will could look like.

The media for development and deployment of the documentation are still TBD, but we’d like to integrate as closely as possible into the existing Eclipse structure.

*** 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!