Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "E4/Doc/ProjectDetails"
| Line 37: | Line 37: | ||
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. | 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 ==== | ==== Establishing A Template ==== | ||
| Line 42: | Line 44: | ||
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 documenation, as it enforced consistent formating and provided a framework for organizing our ideas. | 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 documenation, as it enforced consistent formating 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. | + | 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 suited 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. |
== Non-Code Contributions == | == Non-Code Contributions == | ||
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! | 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! | ||
Revision as of 09:11, 8 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.
Establishing 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 documenation, as it enforced consistent formating 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 suited 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.
Non-Code Contributions
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!