[Lazarus] [fpc-devel] Documentation contribution

Everton Vieira tonvieira at gmail.com
Wed Feb 15 21:22:45 CET 2012


Em 15/02/2012, às 17:52, Martin escreveu:

> 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")

If the end user, could use the IDE to contribute, "writing an example" by example and by clicking in a button this were send to some pool to be checked and then incorpored, then maybe it will be very good. I know there`s a lot to be done to get such a tool, but the idea is good. In an open source project we should always thinking about to make easy and secure the process of contribute. Is better for all.

> 
> 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 at lists.lazarus.freepascal.org
> http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus





More information about the Lazarus mailing list