[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
[platform-doc-dev] summary of Oct 18/2004 doc meeting
|
Here's my summary of yesterday's meeting. I didn't take great notes, so
please correct me if I've misrepresented or forgotten anything.
---jim
===========
Summary of Oct 18/2004 meeting
Present: Michael Behm, John Healy, and Ben Konrath (all of Redhat); Susan
Franklin, Michael Van Meekeren, Andrea Covas, and Jim des Rivieres (all of
IBM)
- Redhat currently edits the doc books for the Eclipse Platform, JDT, PDE,
and CDT to make them more suitable for inclusion in their Eclipse
distributions. Redhat is offering these changes back to Eclipse, and
ongoing help on the doc front. The purpose of the meeting was to discuss
how best to fold back these changes into Eclipse, and how best to
collaborate on doc.
- Michael B. began by walking everyone through the changes he made to 3.0
(he did the same sort of thing for 2.1 as well). These changes run the
gamut: replace Windows screen shots with Linux ones; normalize HTML tags
so that files validate; and copy edit to fix typos and improve exposition.
- The standard doc is intended to be "multi-platform", but with the
assumption that most readers will be using Windows. The standard doc
includes explicit tips and pointer for readers using other OSes. In
contrast, the Redhat version of the doc is geared to readers that are
using Linux. All screen shots are of Linux (Bluecurve); references to
files etc. follow Unix naming; tips for Windows, Mac, etc. are omitted.
- We agreed in principle that the ideal outcome would be to eliminate the
need for Redhat to change files in the doc plug-ins. The bulk of the
changes should be incorporated directly in the standard doc. Element
class="" attributes can be used to mark platform-specific HTML passages;
cascading style sheets can then render these suitably for a given
platform. The best way of handing screen shots from multiple platforms is
a challenge that will need to be addressed. A strictly additive approach,
like NL fragments, would be good (if feasible). Action: Explore our
options with Konrad K. (Eclipse Help); report to
platform-doc-dev@xxxxxxxxxxx.
- We discussed whether we should use our own XML-based format for all doc
files, instead of plain HTML. While this would make it easy to write tools
that generate HTML suitable for any particular platform, it would also
make it harder to use existing HTML editors like Dreamweaver. So we
decided to stick with the current approach.
- We agreed that there should be a style guide for the Eclipse
documentation. Redhat has drafted one (based on the CDT User Guide Style
Guidelines
http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/cdt-home/user/docs.html?cvsroot=Tools_Project
). These guidelines will need to be augumented with details about the HTML
tags for platform-specific elements, how to handle screen shots, etc. Once
details are worked out, the guidelines should be offer for adoption by all
Eclipse top-level projects. Action: Redhat to circulate their draft to
platform-doc-dev@xxxxxxxxxxx for discussion.
- We agreed that this work should happen in the 3.1 development stream
(HEAD).
- We agreed it would be good to have Eclipse-based tools for validating or
otherwise checking doc files. If we had such tools, committers should
perform these checks before releasing changes to doc files; and these
checks should be incorportaed into standard releng builds. No one has
signed up to write tools at this point.
- Once we've worked out style guidelines and the solution to the screen
snaps, Redhat will submit modifications to the exisiting doc as patches
attached to a bugzilla report. These changes will be reviewed by
committers and applied to HEAD. Redhat will flag those files containing
interesting subject matter changes (as opposed to HTML tags tweaks) so
that they can be specially reviewed by the commiters familiar with the
subject matter. In the places where their rewrites have introduced new
screen snaps, they'll include Windows versions to match existing doc.
- Michael Behm has generously offered to help with Eclipse doc on an
ongoing basis, and indicated his interest in earning committer status. His
help would be most welcome. Spearheading the development of doc style
guidelines, and working to push changes into the doc base will be to his
credit.
