Skip to main content

[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.

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


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.

      -     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

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

*     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:

Back to the top