Project Goals & Definition
The goal of this project is two-fold: Unearth and refine a process for creating Eclipse 4 Core Application Services documentation and with a process in place, document as many of the services as possible.
The project is part of a fourth year technical communications course in the Computer Science program at the U of M and runs from January to April of 2010.
Development of the documentation occurs on this wiki. Upon finalization, the wiki pages will likely be converted into the Eclipse Help format.
Due to our (the students) limited existing knowledge of the platform as well as relatively short time constraints, it would be unfeasible to assume we could be the single source/aggregator of all relevant and applicable knowledge relating to the services. Instead, we go right to the source and interview the developers of the service. We have (phone) meetings and essentially are "taught" what the services do and how they work. We then individually and collaboratively take the knowledge gained in the interview and turn it into documentation on this wiki.
We believe this to be an effective process as it highlights and solves the key problem we are trying to solve. Like the future readers of our documentation, we know little about each of these services or at least how they are done in E4. By having the developer of the service teach us, we then ideally have gotten all of the pertinent information that we needed to learn the service and conveyed it accurately and concisely in the documentation.
For each service we conduct hour-long phone interviews with one of the major developers on that service. This hour is akin to a lecture on the service and has the developer basically answering the question "What is <insert name of service>?". These interviews have been very successful as we are getting the most up-to-date information and in a casual easy to understand form. The interviews usually begin with some background information and the explanation of the major motivation for the service which then sets the stage for understanding how it works and how to use it. The informal format of discussion is also nice because it allows us to ask any pertinent questions as we go along. Furthermore we found it very useful to have more than one interviewer as we found we often differed upon interpretations of what was said by the developer and were able to have discussions surrounding it. Furthermore we found each of us would pick up on different details during the interview and having more than one person there allowed a greater amount of information to be captured.
- IBM Eclipse Developers
- Mike "McQ" Wilson
- Boris Bokowski
- John Arthorne
- Susan Franklin McCourt
- A team of University of Manitoba students and their prof
In Retrospect: Lessons Learned
Writing technical documentation for unreleased software presents a formidable challenge, particularly when undertaken for the first time. An evolving product presents a moving target for documenters, who must keep apace of continous change. When writing about previously undocumented software, a common framework must be established, and information must be gathered directly from the people who possess it.
During our semester-long experience of documenting Eclipse e4, we encountered each one of these difficulties. With our delivery of a reusable template and several documented services, we have also identified a number of insights which will be valuable to those who come after us.
Identify Project Goal
One of the most important aspects of a successful project is a unifying goal. Although many project requirements must be defined as a project evolves, a high-level goal provides a measure against which progress can be measured.
In our first meeting with the Eclipse team, we were told to write documentation that focuses on the high-level, code-independent design of e4's services. This goal became a recurring topic of our team discussions as we evaluated how our efforts worked toward its accomplishment.
Establish A Template
We found it necessary to establish a template early in the documentation process. Our template was a useful guide for both information gathering and writing. While interviewing Eclipse developers about application services, our template helped us formulate questions that would yield suitable information for our writing. Our template was also a crucial component of writing documentation, as it enforced consistent formatting and provided a framework for organizing our ideas.
Developing a suitable template was a challenging task, and our first attempt was unsuccessful. A good template must be suitably restrictive; a template needs to be general enough to apply to a range of topics while still enforcing consistency and providing useful guidance. To arrive at our final template, we consulted a variety of existing professional documentation, and adopted practices which were applicable to our project. We found the legendary Design Patterns book (authored by the "Gang of Four") to be a particularly useful model for documenting software conceptually.
Define the Learning Process
Because our project involved documenting software which we did not develop, learning about our subject matter comprised a sizable portion of our effort. When we first approached the subject of information collection, we decided to passively solicit information from the Eclipse community (using mailing lists, wiki pages, etc). We quickly realized that this approach would not work. A broadcast-style request is not only ineffective in garnering responses, but also proves inadequate when very specific information is required.
Having identified the problems with our approach, we decided that it was instead necessary to gather information about e4's services from those who were most familiar with them. We performed a series of hour-long phone interviews with two e4 service developers (Susan Franklin McCourt and Boris Bokowski), and the results were much improved. Susan and Boris provided us with a comprehensive understanding of each service, and the "one-to-one" communication style allowed us to ask the questions that corresponded to the gaps in or knowledge.
When provided with a good template and a full complement of relevant information, documenting an e4 service is no longer an overwhelming challenge. Still, our experience uncovered a few insights into the subtleties of collaborative writing.
In an effort to capitalize on the combined abilities of our team, we initially attempted to write service documents as a group (akin to pair programming). Although essential for outlining our ideas and editing our work, our group writing sessions proved to be cumbersome for actual composition. Constructing a sentence from an idea is a complex task, and does not translate well to a group effort. In the end, we settled on a writing process where composition was done individually and supporting work (such as editing, etc.) was accomplished as a group.
This was one of if not the first time the Eclipse foundation has received community contributions that are not code based. We hope that our experiences are able to serve as a guide for others looking to contribute in similar fashion in the future (perhaps to finish what we started!) and hopefully to encourage some "softer" contributions to the Eclipse Foundation as well. To put it simply: we have shown it can be done!