Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "E4/Doc/ProjectDetails"
| Line 1: | Line 1: | ||
| + | == Project Specification == | ||
| + | |||
===Project Goals & Definition=== | ===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 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. | ||
| Line 29: | Line 31: | ||
**Stefan Dimitrov | **Stefan Dimitrov | ||
**[mailto:hildebrand.c.m@gmail.com?subject=e4%20documentation Chris Hildebrand] | **[mailto:hildebrand.c.m@gmail.com?subject=e4%20documentation Chris Hildebrand] | ||
| + | |||
| + | == 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 lessons which will be valuable to those who come after us. | ||
| + | |||
| + | ==== Establishing A Template ==== | ||
Revision as of 20:06, 7 April 2010
Contents
Project Specification
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 development of the documentation is a collaborative effort between a team of computer science students at the University of Manitoba and the wider Eclipse community.
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.
Medium
Development of the documentation occurs on this wiki. Upon finalization, the wiki pages will likely be converted into the Eclipse Help format.
A list of existing wiki pages is kept here. The documentation for each application service resides in its own page and conforms to this template.
Process
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.
Collaborators
- IBM Eclipse Developers
- Mike "McQ" Wilson
- Boris Bokowski
- John Arthorne
- Susan Franklin McCourt
- A team of University of Manitoba students and their prof
- Prof. Christina Penner
- Brent Barkman
- Stefan Dimitrov
- Chris Hildebrand
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 lessons which will be valuable to those who come after us.