Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [wtp-dev] What's New and Release Notes

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.

Back to the top