[Lazarus] Documentation contribution

[Hans-Peter Diettrich]

Martin schrieb:

>>> So that people that building the CHM and press F1 don't have to read 
>>> "[what?]"
>>
>> You seem not very familiar with writing documentation?
>> Notes are ignored unless brought into sight every now and then. Did 
>> you e.g. read StyleGuide.txt?
>>
> Then we need to extend fpdoc. So we can build help (chm or other), with 
> or without todo/notes

That's the reason for the cross-post, after I had just this idea.

> Yes it is true, everyone who wishes to write/contribute docs does need 
> to see them. Even more: there is a need for an overview (like the todo 
> list win for pascal todo)

I wouldn't go so far. ToDo's also are ignored frequently, as well as 
compiler hints and warnings, and adding such a feature will require more 
tools. For more comfort we should use an readily available CMS, not 
extend the dedicated FPDoc tools. IMO it will be more efficient when the 
*users* complain about strange elements in the documentation, so that 
finally the *competent* developers will fix these issues.

> But, any doc to the end user must not contain this.
> It is useless, even irritating to the help seeking user

To me it's more irritating and confusing, when documentation has already 
been found wrong, without any according indication.


> True the entry without the note is already of little, maybe even no use.
> But a user seeking help, getting presented, with a out of context, 
> single word question "What?" is worse. Remember the user does not know 
> that this is a comment meant for the develeopper. The user assumes, that 
> this "What" is some form of hint, that should help him understand the 
> topic.

Here I think you're underrating the Lazarus users :-)

> So we face the question what to do until such a todo-note feature exists.

Why not leave the notes as they are? If everybody would fix such a note, 
instead of discussing how to proceed, we would have nice and better 
documentation pretty soon ;-)

DoDi