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<[email protected]> 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 > [email protected] > http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus -- _______________________________________________ Lazarus mailing list [email protected] http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
