Re: [wtp-dev] What's New and Release Notes

[David M Williams <david_williams@xxxxxxxxxx>]

We are talking about two documents,
right? Two audiences? 

I think a "new and noteworthy"
document is for end-users, each component (lead) creates end-user highlights
for that component, and someone pulls together a "table of contents"
to link to each individual one. For some new items, such as web services,
I'd think this would mostly point to other, "stand-alone" tutorials,
etc. that walks end-users through some basic "how to" steps.
For existing features, such as validation, just new things, such as new
preferences, etc., would be highlighted. [I think our introduction of "tutorials"
in last milestone is a great way to document and test our main path functions!]
This "new and noteworthy" document is the place to look cool,
"show off" neat function, and., again, should be oriented to
less technical end users. 

The release notes -- I think same as
build notes (right?) -- is more for developer and add-on audience and would
include new or changed APIs, bugs fixed, etc. There's been discussions
of automating/standardizing this, but, since hasn't happened yet, I don't
think it will, and, in my view, is not worth the effort. I think this sort
of standardization is like code ... should only be standardized after some
experience with it and only if there's an obvious need, otherwise let each
component do what they think best. 

So ... there's a little known secret
of our build process that will work without further ado. You can add a
file to your project "root" named 'buildnotes_'<componentname>'.html'
and it will be pulled into build notes on the build page for that build.
I've added buildnotes_sse.html in org.eclipse.wst.sse.ui to test this and
make sure it works (see I20050222). The base Eclipse has many examples
of appropriate level of content.  I would recommend we use strict
XHTML, just in case anyone wants to parse and transform it (well ... there
I go, recommending standards after I said I wouldn't :)  This would
be the document to keep up, week by week, adding a new section above the
existing ones, so at the end of the milestone and release you have a record
of the whole milestone and release. There are some things, like the list
of bugs, that's tempting to automate, but in reality, its pretty easy to
copy/paste from your own bugzilla queries. Again, my own view is its fine
for each component to document how they see fit and the "one document"
is done simply with links.