[Lazarus] Documentation style

[Hans-Peter Diettrich]

During the development of the doc tracker I stumbled over several issues:

The English wording often violates my feeling for the language. Can some 
native English speakers proofread the documentation, and correct 
stylistic flaws?

I don't want to discourage non-native speakers to contribute to the 
documentation, but they should mark their entries as "raw" (to be 
revised), so that a proofreader can easily find and check new or updated 
entries.

I already started inserting markers into the docs, e.g. [?] for 
questionable and [???] for obviously wrong parts, and more [revised ...] 
notes. Accordingly above "raw" marker could e.g. read [~], and should be 
inserted wherever questionable wording has been found.

Style related are field names like "childs", which IMO should read 
"Children" (which was the name in the preceding document version!). IMO 
the core developers *also* should consult native English speakers, 
before adding items with poor names.

Often I come across "circles", referring to circular unit references. 
IMO the correct term instead would be "loops", in e.g. "avoid loops".


Many descriptions only describe the obvious, like method names expressed 
in more words. Such descriptions are quite useless, and should be 
replaced by more informative ones. I'd suggest to remove all these 
descriptions (replace by a todo-marker?), until somebody can describe 
the elements better.

The final documenation shows the element name, so that the short 
description should not duplicate this name, IMO. Opinions?

Related: the FPDoc Editor IMO should always show the short description, 
above the pages. Then it's easier to e.g. avoid duplication of the short 
description in the long description.

What's the purpose of the *used units*, listed as elements of some units?

The same for parameters, whose separate descriptions are not normally 
accessible in e.g. the FPDoc editor. While it may be nice to have all 
parameters (and Result) described explicitly in the final documentation, 
the separation of these items from the procedure description is not 
helpful for the documentation writers. I'd suggest a description list 
for all parameters and the result, inside the long description. Such a 
list would make the docs look more like the (old) Delphi or MSDN 
documentation, with a clear structure for all subroutines:
- short description
- declaration (maybe multiples for overloaded procedures)
- parameter description
- result description
- long general description

What's the purpose of the "Errors" tag?
IMO it should not only contain links to the possible exceptions, but 
also should describe the exact reason, when an exception is raised. And 
it also should contain remarks on yet unhandled situations, which can or 
will cause an AV or wrong results.

As already mentioned in another mail, all links to #LCL are broken now. 
I hope that this will be fixed soon, by renaming the packages.


So much for now. I'm willing to coordinate all work on the 
documentation, and hope to get back write access to the repository soon. 
Then everybody can send me patches or notes on the documentation. Don't 
hesitate to report missing documentation or details; documentation 
writers often are so familiar with an topic, that they forget to mention 
the basic details, which are unknown to the *users* of the described 
elements.

I also can assign doc files to those people, which are willing to 
proofread the documentation, so that we can avoid duplicate work.

DoDi