[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
[eclipse-dev] 2.1 Documentation Effort
|
Now that we are slowing down on code changes we will
get the documentation effort rolling.
This document outlines the overall plan and
includes a check list of items that need to be
done for 2.1. This check list should help
components to come up with their own more
detailed documentation plans.
The overall goal is that the documentation is correct
and that we preserve the 2.0 quality and
completeness level.
Communication on doc issues will take place on the
platform-doc-dev mailing list, so please subscribe
to this mailing list for discussing documentation
related issues.
For editing the HTML content DreamWeaver is our
recommended tool.
The document is also a first attempt
to collect all the tools that the different
teams have developed that help in the checking pass.
So if you know of additional tools then please
let us know.
TIME LINE
Week of March 17th
At least one team member works full-time on the doc
* focus on documentation contents. Goal is to have
most of the contents done. We really
want to get started with contents this week
and not wait until next week.
* finish code related documentation for the RC3 build
- javadoc
- properties files checking
Week of March 24th
Everybody works on the doc
* documentation finish
- contents
- help context id linking
* documentation checking/testing
TO DOs
User Doc
* Review and spell check the messages in the
.properties files. These messages are important
user documentation and we should treat them
like that (see below for a tool that can
help on this issue).
* Check the Welcome page for accuracy.
The welcome page should include a link to all the
icons used by a component. The list of icons needs
to be updated for 2.1.
* Update the getting started documents.
The getting started documents have to have high quality and must
read well. Users have to be able to become productive
by reading the getting started docs.
* Complete the getting started document set
for areas that are currently not covered
in a getting started doc (e.g. Ant, JUnit, ...)
* Redo all the screenshots.
Tod takes the lead on this and he will send out
the common set-up for taking screen shots. He will
will help with existing screenshots. Teams will be
responsible to create new screenshots following
the standardized set-up.
* New: Complete the What's New in 2.1 section.
These should be in the same format as the New and
Noteworthy document. Jim has added a corresponding page
and added some initial contents.
* New: Add a Tips&Tricks section.
The tips and tricks are available from the
Help menu. For each feature there is a corresponding
page in the doc.
Jim has already released contents to tips and tricks
pages based on the New and Noteworthy documents.
To quote Jim:
This section should make interesting bathroom reading for
an end user of Eclipse 2.1. It should give them bits of
advice on how to use Eclipse effectively. It should stay
away for things that a user would naturally discover while
using Eclipse, and instead focus on high-value
things that they might not have noticed. It also
differs from the "New for 2.1" section in that it deals
with anything in 2.1, not just the new stuff.
Style:
- Each item should stand by itself.
- Each tip answers the question
"Did you know...".
- Illustrate the tip with a screen shot
and a couple of sentences.
- Make it easy for the user to apply a
trick immediately.
* Finish and check the help context ids for new
Actions/Wizards/Dialogs etc.
* Link the new help context ids with the user documentation.
No context id should link to a page
that only contains links but no text.
* Tasks, Concepts and Reference section:
Make a pass to ensure that they are correct, remove obsolete
sections. Since these sections are mostly targets for F1 help
we will not spend cycles on improving the readability of these
sections. In other words the main focus should
be on the New sections: tips&tricks, what's new and
the getting started documents.
ISV Doc (javadoc, extension point description, examples)
* javadoc - all APIs must be javadoced.
New API added in 2.1 must be tagged with the @since 2.1
* Review and complete extension point descriptions
in the schemas
* Review and update the Plug-in developer guides
* Add descriptions of new API in the corresponding
programmer's guide
* New: Weave in API related articles into the documentation.
We have several articles that describe how to use
the Eclipse API (e.g. Launch Config Article,
several SWT articles). We have to make sure that
developers can find them from the online doc.
To do so each article should be listed
with a short abstract in:
Developer Guide>Reference>Other Reference Information.
* Check the examples, example descriptions
Documentation Checking/Testing
* The getting started documents need to be tested
by having users going through them step by step.
* Link checking of all documents. This includes the
link checking between the help context IDs links and
the documentation (see below for tools).
* Accessibility checking
The documentation has to be accessible.
* No mixed line delimiters
TOOLS
This is the initial list of tools we know of.
* DocEditor (contact: Veronica Irvine)
Tool that helps to keep the help contents consistent.
In particular it helps you with "doc refactorings".
* ExportPropertiesValues (Dani Megert):
digests .properties files so that they
can be spell checked by a word processor's spelling
tools.
* MixedLineDelimiters (Dani Megert)
Fixes mixed line delimiters
* TopicToHTML: (Dani Megert)
converts the context.xml files (storing the
help contextID - doc links) into html so that you
can use the link checking of an HTML editor
to check for completeness
* HelpContextId: (Dani Megert)
a tool that correlates the help context IDs in the
contexts*.xml files with code help context ID
constants defined in an interface.
* Accessibility testing:
Bobby: http://bobby.cast.org/html/en/index.jsp
