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.
E4/Doc/Template
The evolution of this document is a collaborative effort between a team of students at the University of Manitoba and the wider Eclipse community. Details about the project can be found here and on our Blog.
Your input is not just welcome; it is needed! Please contribute as your expertise allows, while adhering to our template. To send your feedback and any questions or comments you may have please email us. Also, while we do our very best to be as accurate and precise as possible, it is worth noting that we are students with limited exposure to the Eclipse platform, so if you see any incorrect technical details please let us know.
Contents
How To Use This Template
To begin, navigate to the URL of the service you wish to document. If it does not exist yet, the wiki will bring you to a blank page that you can start working with. Choose the 'Edit' tab and copy and paste the markup of this page (less the 'How To...' sub-sections) into the new blank page. Replace the text for each section with the relevant service information.
How To Work With Images
PNG format images are uploaded using the Upload file link on the left (in the Toolbox section). Both the PNG image and a zip archive containing the original Open Office ODG file are uploaded with the same name (but different extensions). This allows you to download editable copies of the existing images. When creating new images, we suggest that you start with an existing image and modify it so that the colors, sizes and fonts remain consistent. When exporting the PNG from OpenOffice we have found a compression level of 6 achieves the optimal quality (the image is resized on the pages) vs. size ratio.
Both a general and eclipse-centric description of the service go here.
Relevant Terms
- List - and description of
- Relevant Terms - goes here
- Things - like Eclipse'isms or terms that would be useful and commonly found in discussion about this service both generally or Eclipse specifically
Motivation
What problem does this service solve? What is the use case that it makes easier? This section essentially conveys the 'WHY' behind the service.
Applicability
Where does this service apply? What situations is it useful in? DO NOT mention code or api here. The goal is to be code agnostic.
Implementation
The details surrounding actually consuming or contributing to the service as well as tips and tricks.
This is also where the code samples will live if there are any. However, USE CODE SAMPLES SPARINGLY and only when they are the best way to convey a point. The goal of this documentation is to be code agnostic.
@Inject MSomething; public void foo() { }
History
For many services it is useful to know how the e4 versions related to 3.x and previous versions of the service but at the same time too overwhelming for new Eclipse developers if you intermingle this information with the existing e4 documentation. This section is meant to alleviate that problem by providing a spot for historical service information for the readers who wish to view it while not encumbering new developers with less than pertinent information.
Related Services
- A hyper-linked list of related services that will provide the reader with relevant information when they are consuming this particular service.
- It is rare that this section will be needed but in the case where two services appear to be very similar but in fact are very different, you should list and describe it here.