[Lazarus] [fpc-devel] Documentation contribution

Hans-Peter Diettrich DrDiettrich1 at aol.com
Thu Feb 16 16:31:54 CET 2012


Martin schrieb:
> 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)

I.e. you ask for perfectly formulated and clear comments *about* the 
flaws in the existing documentation *only*, while the previously 
existing documenation is accepted in any state (misleading, incomplete, 
wrong...)???

Needless to say that I cannot share that VP. I don't want to write 
another Ph.D. thesis about the docs. See also 
http://en.wikipedia.org/wiki/Copy_editing


> 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.

What other solution do you suggest instead? Remove crappy or 
questionable content, instead of only adding 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.

I see an documentation review as an invitation to improve the existing 
documentation. If some notes look too short or otherwise unclear, 
everybody is free to ask the reviewer for a clarification. As long as 
only I added [...] notes, it's clear who can answer related questions. 
When an entry was found misleading or otherwise poor, in most cases 
*not* the author of that part is capable or responsible for fixing it, 
instead people with detailed knowledge about the *subject* or *language* 
should put their hands on it.


> We can always offer 2 (or more) versions of the help. With/Without notes

My intention was a feature in FPDoc, that allows to hide my notes, based 
on the clear [...] syntax. The --emit-notes option perfectly reflects 
that now, but only for an *out-of-line* <notes> section. A better 
alternative could add an tag for *inline* comments, like the existing 
<var> or <b> attribute tags. A <strikeout> attribute would come close to 
my intention, to indicate both the range of the affected text, with a 
note (attribute) inside the tag telling the reason why.

DoDi





More information about the Lazarus mailing list