[Development] Documentation of new Qt features in qtdoc

[Edward Welbourne]

On Mon, Nov 22, 2021 at 10:43:45AM +0000, Edward Welbourne wrote:
>>> Documenting it while it's fresh in your mind generally leads to a
>>> better description, after all,

Oswald Buddenhagen (22 November 2021 12:47) replied:
>> i'm not so sure about that. as seen by the quality of the [ChangeLog]
>> entries (in as far as present at all), many people have problems
>> switching their perspective to the different audience. doing that
>> with some temporal distance might actually help (though the "spatial"
>> distance of it being in a different repository certainly also helps).

The other virtue of putting the comments into a repository, rather than
commit messages, is that it opens up the option of revising them later.
So the initial description of the new feature in qtdoc may well be given
from a perspective too close to the work; but Kai's plan is to have it
in a shared repo where others (who might not have been involved in the
original review, to suggest improvements to a ChangeLog) are going to
edit the same document to add their own new feature descriptions, so
might see the deficiencies of existing entries in the file and either
improve them or poke the (by now long closed) review that added them to
ask what was meant.  So there's scope for improvement between when the
work is first described in the communal document and when that document
is finally published - just as in the wiki, but with the benefit of
past reviews on which to ask the questions and point out the problems
with particular edits to the file.

Shawn Rutledge (22 November 2021 15:56) added:
> ChangeLog entries from the git log may often be badly-worded or be
> written badly for the audience that’s going to read them, but I think
> we should still start from those, for the sake of completeness.

I think the aim here is to make them (and all scripts with delusions of
collecting them into a useful release story) redundant in any case.

	Eddy.