Sign in Join

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Mailing lists / lazarus / 2010-10

fragmented documentation causes lots of frustration

3 messages · 2 people ·

Reply by email Subscribe to this list Your subscription

Read-only archive. Use j and k to move between messages.

Graeme Geldenhuys

To the Lazarus team,

You guys should really decide what you want to use as a help medium. The wiki OR fpdoc class documentation. I don't use LCL much, so when I do, I need lots help. Pressing F1 in the IDE takes me to the class documentation where I would expect to see help. Take the TStringGrid as an example. There is absolutely NO help in the fpdoc class documentation, so pressing F1 in the IDE is useless. I had to then manually search through the wiki (luckily I know about the wiki) to see if there is any information. Oh by the way, wiki search support is crap too.

Anyway, lucky for me the wiki contained lots of help on the StringGrid options etc, but that help should really be in the developers "first port of call" - the medium that is displayed when I pressed F1. Currently that is fpdoc class documentation.

I'd suggest you take some time out of developing nice new features in the IDE, and rather get your house in order. Sort out the damn documentation mess. I'm pretty sure you guys know how important documentation is. And currently the little help there is in LCL is fragmented too - a double whammy! Some docs in fpdoc class files, some on wiki, some in blogs etc... Learn from Borland's mistakes; a framework needs documentation, and only one set of pooled documentation too. I know your resources are spread thin, but that is more the reason to keep the little available help there is in a single location and single medium.

If your answer is that the wiki is simply easier to use that fpdoc editor, then why not create a wiki frontend to the fpdoc class help. LufDoc (from a guy name Lars) did something similar so it is possible. That might even double up as a good "sample project for fclweb" or whatever the web controls are called.

Just my 2c worth...

Regards, ? - Graeme - _______________________________________________ fpGUI - a cross-platform Free Pascal GUI toolkit http://opensoft.homeip.net:8080/fpgui/

Reply by email

Michael Van Canneyt
to Graeme Geldenhuys
Graeme Geldenhuys wrote
To the Lazarus team,

[snip]

Show quoted text 6 lines
If your answer is that the wiki is simply easier to use that fpdoc editor, then why not create a wiki frontend to the fpdoc class help. LufDoc (from a guy name Lars) did something similar so it is possible. That might even double up as a good "sample project for fclweb" or whatever the web controls are called.

If someone wants to start on that, I'll be glad to help out with the fcl-web implementation.

Michael.

Reply by email

Graeme Geldenhuys
to Graeme Geldenhuys: You guys should really decide what you want to use as a help medium. The wiki OR fpdoc…
Graeme Geldenhuys wrote
If your answer is that the wiki is simply easier to use that fpdoc editor, then why not create a wiki frontend to the fpdoc class help. LufDoc (from a guy name Lars) did something similar so it is possible.

Just to be clear. What I meant with the above is a "web frontend" to editing fpdoc xml files (class documentation). After the fpdoc xml files are edited, the HTML class help should be automatically updated (or maybe every 10 minutes via a cron job if resources are low).

Here is some information on LUFDOC.
http://z505.com/cgi-bin/mse/idx.cgi?file=fpdocintegrated

LUFDOC even supports searching...
http://z505.com/cgi-bin/powtils/docs/1.6/idx.cgi?file=lufindtool

If you were wondering what LUFDOC stands for: Live User Fed Documentation

Regards, ? - Graeme - _______________________________________________ fpGUI - a cross-platform Free Pascal GUI toolkit http://opensoft.homeip.net:8080/fpgui/

Reply by email