On Thursday, January 03, 2013 19:18:25 Walter Bright wrote: > As for what's new, the failure here is the failure to document those > changes. This is not a failure of the changelog - it's a failure of the > documentation pages. The bugzilla should have a link to the relevant > documentation. > > I do *not* think that a changelog new feature entry takes the place of > updating the documentation, and I do not agree with writing the > documentation twice (changelog and documentation).
In general, the only "new features" which need to be in the documentation but don't end up there are in dmd. But even then, they need to be in the changelog or release notes - preferrably the release notes, if we're separating them. I expect that very few people will comb through the list of bug fixes. They want to know the highlights, and we should list those. And _no one_ is going to dig through the documentation to try and figure out what changed. So, omitting a new feature entirely from the changelog or release notes because it's been put in the updated documentation makes no sense. The changelog and release notes definitely do _not_ replace proper documentation, but they're a necessary companion to it when new features are added or major changes are made. - Jonathan M Davis