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