[fpc-devel] [RFC] fpdoc output comment from the source

L505 fpc505 at z505.com
Sun Dec 4 05:01:46 CET 2005

> > The way to get users do
> > more work in writing
> > documentation, is to have a comment system right up live on the
> > website. Even the PHP
> > manual does this ;-)
> yeah the accuracy of said information leaves a LOT to be desired though
> imo if this is done someone needs to be resposible for looking at the
> comments and checking they are factually accurate.

For sure. The comments are in a different color than the actual "fixed"
documentation. It will be clearly stated that "these comments are from users and are
not necessarily correct. Users make their best effort to make accurate comments, but
occasionally there may be an error".

When an major and important comment from a user is submitted, the docs are recompiled
with the new changes. This way you get a fixed factual style documentation, along
with user contributed comments. The main problem with FPDOC the way it is now, is
that no FPC user in their right mind is going to spend 15 minutes - 3 hours
recompiling the entire FPDOCS just to make a small spelling mistake change or add a
small and useful comment.

And you think the FPC user is actually going to mail the mailing list with a patch to
the docs? Go to all that work and spend hours of his time figuring out how to make
and send a patch? People are lazy.. they want to update the documentation right
inside little Internet Explorer, Opera, or Konquerer, or ultimately a thin client
;-). I've not actually started working on this project but it's called LufDoc, and
I've got all the framework/basics laid out of what the system is, what it will do,
and how it will work. I just have too many other things to do right now... I think I
will work on this at some point when I'm done fiddling with Syn text editor and PSP a
bit more.

More information about the fpc-devel mailing list