Re: [flame] NEWS file is useless

[Richard Frith-Macdonald]

On 26 Nov 2009, at 11:03, Nicola Pero wrote:

> 
>>  It would be good to consider exactly how much (if any) information we want 
>> to present in NEWS/ReleaseNotes ... my preference would be for minimal 
>> information there, and a pointer to a generated ChangeLog for details.
>> This would require a policy that svn log entries should be suitable for app 
>> developers (users of the libraries), not just for people writing the 
>> libraries themselves
> 
> 
> I agree that it would be good to have ChangeLog entries that are well written 
> and readable by people who are not working on the software themselves :-)
> 
> I still think NEWS (and/or Release Notes) need to be written separately as an 
> additional task.  We shouldn't be lazy with documentation ;-)

Yes, I think we need somethings, but as I said I'd like is 'minimal' ... an 
overview rather than the sort of detail in the ChangeLog.
 
> I guess it depends on the piece of software, but for example our core 
> libraries have a large user base, and it's worth
> spending some time writing clearly readable NEWS/ReleaseNotes.  If you don't 
> write them, you'll spend 10x the time answering
> questions via email about changes to the library anyway, so it even saves 
> time in practice to spend time documenting
> changes! ;-)

Well, ideally I'd like that sort of detail to be in the ChangeLog (and as I'm 
advocating generating the ChangeLog from the svn entries, that means I'd like 
information in the svn entries going into helpful detail).

> Finally, NEWS/ReleaseNotes are important for marketing - any time we 
> implement something good, we should tell the world!
> NEWS/ReleaseNote tend to for the basis for public announcements or tend to 
> end up on websites etc. so we should work on them.

Sounds right to me ... the place for a publicity overview rather than technical 
detail.  I think that should be kept short and easily quotable.

> 
>> Lastly ... I'm not even sure that the historical policies on ChangeLog etc 
>> are written down anywhere
> 
> They are part of the GNU Coding Standards, 
> http://www.gnu.org/prep/standards/html_node/Change-Logs.html

Thanks.