[Lazarus] documentation snapshot

[Graeme Geldenhuys]

On 2013-04-20 19:58, Anthony Walter wrote:
> The benefit of online docs ...
> 
> Anyone can access them without installing a thing (assuming people have a
> web browser, which everyone does).

Unless your internet goes down... like what happened to me on Thursday.
And I live in a first world country (finally) - but not even such
countries are immune to internet outages.


> This allows people to peruse/browse
> before they try, which is what most people do,

I supply pre-built binary downloads of DocView and some INF help files -
for just that reason. They can download the source code of fpGUI and
built everything themselves, but I save them the trouble. And DocView
has no installation - just run the executable.

Also the docview resource usage is a fraction of what is needed by these
bloated web browsers these days.


> Since online docs are online, they become easily queryable via everyone
> default search tool (google, or bing or whatever).

And they are only has "up to date" as the last time Google or Bing
indexed the "whole site". If you update the documentation now, you have
on idea when Google will index your site again. It could be a day, it
could be a month or more. So searching support is dependant on an
external entity that doesn't care about you.


> Online docs can be updated/corrected/added to without sending needing to
> download updates/patches.

Macro replied to that, and I agree with him.


> download, I will most certainly add tutorials/how-to's to help (which are
> cross referenced inside the help) after the fact.

Cross-referencing between INF files are supported since the inception of
the INF format. The RTL and fpGUI INF files also have "additional"
non-API topics in the help - already supported by fpdoc. INF is like a
combination of a Help Format + eBook, and works perfectly in both context.

> And for people that are offline some of the time, you can always offer the
> ability to download the help to a folder,

And then can't search - which programmers do often in help files.

Either way, my major grip with online help is that it lacks lots of
functionality I need. Speed, advanced searching with match ranking (and
word match highlighting), indexing, bookmarks, context aware, and
especially annotation (adding personal notes), I have a lot of personal
inline notes added to INF help files, especially the FPC's RTL docs.
These notes are stored in a separate file, but DocView embeds them into
the help topics as I read.

See the first screenshot on this page. The yellow text is highlighted
search matches, the green text is personal notes/annotations embedded
into the help text.

  http://fpgui.sourceforge.net/screenshots_apps.shtml

Anyway, the URL you posted looks pretty. That's all great, but there
isn't much point if documentation looks pretty, but is slow and lacks
vital functionality. That is my main argument. Luckily fpdoc supports
lots of output formats, so I guess end users could generate whatever
format they prefer (if they go to all the trouble).

Regards,
  - Graeme -

-- 
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/