[platform-doc-dev] What needs to be done for R3.1 doc.

[Mike Wilson <Mike_Wilson@xxxxxxxxxx>]

I'm hoping, at this point, that everyone's
R3.1 doc efforts are already going full blast. Listed below are some general
rules to apply when doing your doc, plus a list of all the doc items that
we need to produce. Please let me know if anything below is incorrect/incomplete.

McQ.

--------------------

General doc/HTML rules:

• The deadline for doc is RC3 (June 24th). Getting as much as possible finished for RC2 makes it more likely that it will get wider review.
• Each team is responsible for all documentation related to their component(s). A representative from each team should send me a note once their doc work is finished. Please make an effort to look at as much of the related doc as possible. Also, if there is a section that you believe might not be looked at by someone else, consider looking at it yourself, or at least ask about it on the doc mailing list.
• Every team should check that their views and editors produce valid content in the new dynamic Help view.
• Daniel Megert can run his link checker tool which crawls from top down and reports all broken links taking upper/lower-case into account. If we get him to do this, he'll also directly fix the broken links. I assume we all want him to do this. He also wrote a very simply tool to ease properties file spell checking, which you can ask him for if you think it will be useful.
• All text appearing anywhere in the doc should be spell checked.
• Copyright GIFs are no longer required, but they should be replaced with a new meta tag. Tod will be doing this for the platform doc. Please see bug "https://bugs.eclipse.org/bugs/show_bug.cgi?id=99017" for info.
• The markup tags for screenshots should not include width and height specifications.
• Try to avoid making non-useful changes to the html content, so that we can do reasonable diffs. In other words, don't "re-format" the html, or use tools like Word that mangle it. Most people seem to be using Dreamweaver, but Eclipse is also a perfectly reasonable tool (particularly so, now that you can open both the embedded web browser and text editor at the same time)

Screenshots:

• Screenshots should match the current look and feel, regardless of how small the differences are, so many shots will need to be re-taken because of the change in the view menu triangle. All screenshots that appear anywhere in the doc need to be reviewed. [IMPORTANT: If the only difference in a screenshot is the shell icon introduced in RC2, you do not need to reshoot.]
• Screenshot image files should be: PNG 24 ("Save for Web")
• As with the other doc, each team owns the task of producing the screenshots that appear in doc for their component.
• All shots should be done on Windows XP. RedHat can contribute GTK ones if desired and we will include them if they are ready in time. I doubt we will have Mac ones in the near term.
• On Windows, you should use these settings: 1152x768 screen. No windows backdrop, default colours, use the SWT XP manifest

User Doc:

• Review and spell check the messages in all .properties files
• Welcome content: Dejan owns this.
• Review and update all existing Getting Started doc; add in Getting Started doc for new areas
• New and Noteworthy: John Arthorne and I have started working on this. We created a (totally awful) initial version last night by consolidating all of the milestone versions. I'll send it out today so it can be turned into something real.
• What's new in R3.1 sections for each of the Workbench, JDT and PDE user guides. (presumably based on your sections from the New and Noteworthy)
• Tips and Tricks sections for each of the Workbench, JDT and PDE user guides: Verify old tips are still valid. Add new tips based on What's new sections.
• Verify existence/correctness of all help context IDs; ensure they link to useful content in the user doc.
• Tasks, Concepts and Reference sections: remove stale pages, make sure content is correct. All teams should look at this
• Release Notes: John Arthorne is looking at this

ISV Doc:

• Javadoc: finished for all APIs, spell checked, new API tagged with @since 3.1
• Review and spell check extension point descriptions in schemas
• Review and update the plug-in developers guides
• Check that all the examples run, and still represent good coding style. Make sure their descriptions are accurate.
• Review the porting guide for completeness/correctness
• Review the readme file for completeness/correctness