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/ -- _______________________________________________ Lazarus mailing list [email protected] http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
