[fpc-pascal] Re: Documentation

[Reinier Olislagers]

On 18-12-2012 12:15, michael.vancanneyt at wisa.be wrote:
> On Tue, 18 Dec 2012, Reinier Olislagers wrote:
>> However, fpdoc documentation writing is a huge chore for me compared to
>> writing in the wiki so I've decided it's more productive to get my
>> documentation done on the wiki.
> 
> A wiki is never documentation. It's an explanation - at best.
No, a wiki is a way to store articles/text that people can read. What is
in those articles is up to what you put in it.

Of course, a wiki has certain drawbacks - e.g. no structure and the ones
you mention below.
Remember paper documentation though? That has drawbacks, too, some of
them similar to the wiki.

> Usually (not targeting anyone here) it is sloppy, incomplete, not
> maintained,
> no verification of the up-to-dateness possible.
Mostly agreed. In the same spirit: how up to date, complete and actually
helpful is the fpdoc documentation?
As for up to dateness: there is a history on the wiki, so you can check
that.

Your idea of building a (web) interface that lets people easily update
fpdoc documentation and submit the result for approval by a dev and
subsequent implementation makes a lot of sense.

> Writing quality documentation IS a chore. There is no way around it.
I agree.... but I was refering to the document format, not so much the
content of the documentation.
Having to fight with the fpdoc format where I get unhelpful help
messages like
Warning: Target ID of <link> in unit "zipper" is unknown: "<empty>
is a bit too much for me.

So I put my stuff on the wiki because it's much quicker to write and update.


>> http://bugs.freepascal.org/view.php?id=23506
>> ... so if anybody is interested ;)
> 
> I applied the patch, thank you !
Thanks a lot.