[Lazarus] Adding Notes in FPDoc

[Howard Page-Clark]

On 11/2/12 3:04, Michael Van Canneyt wrote:

>>> Within the <notes> tag, you can include one or more <note> tags.
>>
>> Why so complicated? Can you give a *reasonable* example of the
>> intended usage of this feature?
>
> Yes. User notes on a website. This website has been in the pipeline for
> a long time.

The prospect of a website dedicated to discussion of documentation seems 
to me to be a helpful move forward. This mailing list is not well suited 
to detailed discussions of the numerous issues 'documentation' and 
'help' raise, and use of it for that creates a lot of noise that some 
find irritating.
Nevertheless it is one of the major bullets to be bitten before Lazarus 
can consider getting to the 1.0 stage, and so having an interactive 
arena dedicated to it would be excellent, and I hope would move Lazarus 
docs further towards the goal of being adequate if not good or excellent.
FPC documentation has the advantage of being overseen by a single person 
who has the ability not only to produce and maintain the tools needed to 
write the documentation, but is punctilious in writing the docs and 
keeping shiny new code (however good) out of the FCL until it is 
properly documented. Someone who has poured countless hours into writing 
and correcting the existing docs - making that a priority - alongside 
writing much of the original code. Someone who is also good at 
collaborating with other core developers. Also FPC  does not need to 
document or provide help for a complex IDE that is growing in features 
all the time.
I think the Lazarus team lacks an equivalent core person who combines 
coding expertise with the organisational, administrative and English/XML 
writing skills (and available time to marshal all the 
information/databases/people/wikis and so on) needed to produce good 
quality documentation, and good quality help. This is not to knock 
anyone - goodness knows, each does his best - but simply to point out 
what is true for so many open source collaborative efforts: you have to 
work with the people who offer and stay engaged for more than just the 
short term, and who make the time to contribute enough to make their 
contribution significant.
I hope that a new website might help us bring together the best of what 
is in the current wiki and has been written over the years in these 
mailing lists and the already published Lazarus book. A consolidation 
and editing exercise is needed (in addition to documenting the hitherto 
undocumented parts of the LCL), and I believe there are several people, 
myself included, who are ready to help with this task who have not done 
much towards it so far beyond tidying up the worst bits we stumble over 
in the wiki.