[Lazarus] [fpc-devel] Documentation contribution

[Martin]

On 15/02/2012 19:27, Mattias Gaertner wrote:
> On Fri, 10 Feb 2012 14:52:13 +0100
> Hans-Peter Diettrich<DrDiettrich1 at 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