On 15/02/2012 19:27, Mattias Gaertner wrote:
On Fri, 10 Feb 2012 14:52:13 +0100
Hans-Peter Diettrich<drdiettri...@aol.com> wrote:
[...]
IMO notes should not be hidden in comments. I want them displayed also
in the final docs - just as a reminder that some text is not reliable.
Reminders must be clearly marked. A simple [?] can be misleading.
And I would also cut that into 2 categories.
To me a simple Todo does not belong to the end user. (like "Need to
write an example", or "Review English grammar")
On the other hand, the following (in proper English) could be ok:
"This documentation is outdated, the parameters to the function have
changed." (give more info if avail)
also ok "This differs from Delphi"
To add such notes, the reviewer must have at least enough understanding,
to be sure that something is wrong.
A simple "looks wrong to me" or "I don't get that at all" is not enough
to add a note.
If we risk adding false notes (well it can always happen, but should be
as low risk as possible) then what good are the notes? You could not
trust them anyway.
---
We can always offer 2 (or more) versions of the help. With/Without notes
--
_______________________________________________
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
