|
|
|
|
 |
|
| Help Authoring Software / Help Authoring Tools (‘HAT’ - Link collection) If you want to supply your WinDev program together with a well-designed Help system then there are a lot of decisions and plans to be made! A) The tool used to make the obligatory CHM-file which will be used by the program to show the Help to the users off the software. Besides the fact that WinDev already includes a free Help authoring system there are many Help authoring tools available. Prices vary from free to very expensive and features are numerous. I own/ed a number of Help authoring tools and I know what I like and what not. Let me tell you what’s really important to me to have in such a tool, all other features are optional: - The Editor. There are HATs out there without an editor, they mostly rely on MS-Word for production of the raw Help text. Word is not very page oriented and maintaining / editing a Word document with several hundred pages is a challenge. So, a HAT with integrated text editor is strongly recommended. - Warning! A number of HATs are using text editor plug-ins which are not 64-bit compatible and their authors just did not recognize that ‘feature’ of their software. If you test a HAT and if you are planning to use it on a 64-bit Windows, then input more than a full page of text into the editor! Scroll down and edit the last line. - Most Help text contains recurring technical words and phrases. It’s a pain to retype those words and phrases over and over again. Search for a HAT, which can do an auto-complete of such words or recognizes short acronyms which are to be expanded to the full phrase or word. Reduces typos a lot. - The Help text shown in the editor should be plain RTF (font / size / bold / italic / colors etc). It should be possible to copy & paste text from various sources without being forced to re-edit it. It should be possible to change font / size / color etc of a single word in a line of text. Test it. - If you think it is appropriate, test for a spell checker plug-in. Personally, I do not use spell-checkers because technical text in German will show more red underlined words than others. Maybe, English spell-checkers are better in that respect. - Links and Anchors. All editors let you define a link easily. But can you remove the link while retaining the text of the link? Personally, I think that Anchors are very important. Anchors are link-targets and let your software or a user jump to a paragraph of a help page. Warning! Some HATs do not offer insertion of anchors into the edited text. - Images. All images should sit in a common resource folder and changing one of them there should be reflected in all of the Help pages where it previously had been inserted! Some HATs offer a screen capture tool and can resize the captured image with differing quality. The quality of the resized images is crucial!! Images contained in the Help file will increase its size. So be careful! Images should be big enough to let the user understand / read the text of the shown window but the image should be small enough not to add substantial bytes to the resulting Help file. I’m using Easy Thumbnails from Fookes for shrinking images. Note: if you’re publishing your Help on the web too then readers should be able to actually see what’s being written about - you should include a good picture of the described window on the Help page. If you do not plan to publish Help on the web then including screenshots may be superfluous because a user usually calls the Help from an open window - why to show her/him the same picture twice? - Click areas. It’s a lot of work, but for smaller projects it may be nice to have images of windows overlaid with ‘click areas’ - each of them calling the Help page / Anchor of the clicked control. - Flash. Imho, it’s important to have the ability to embed Flash-objects in a Help page. Nowadays, computer uusers are used to viewing videos from various sources. Many software publishers use ‘Demo Creation Software’ which outputs Flash videos for instruction use. It could be impressive if the user could look at a short video explaining certain features or procedures. If you do not intend to use Flash, an animated GIF image could do the same for you - without sound! - Tables. CHM-files essentially are HTML-files, the ‘C’ in CHM stands for ‘Compressed’. A very handy feature of HTML-pages are Tables, in early times of the web many web pages were composed of tables alone. Your Help editor should offer the insertion of tables into Help pages, columnar display of information is much easier that way. - Page templates. Many HATs offer to edit / store / use templates for Help pages. This is a handy feature because there will always be header pages, pages for explaining a certain window and pages with textual advice to the user. - TOC / Keywords. The Search-function of the finished Help file should find all references to certain words - the keywords. You have to decide, which words of your Help are keywords at all. And you have to build a Table of Contents in some way. Both jobs aren’t easy to repeatedly perform, because any revision of your software will ask for a revision of the Help system too! The HAT should offer support for those tasks - as much as possible! Having to define the keywords for each of the Help pages separately is no good idea - think of a document with 500 pages .. - Link Checker. While building the Help you will add / move / delete pages en masse. All pages will contain Links to other pages or even to embedded objects like Flash or Images. It may well be that some link-targets aren’t existing anymore on compile time. While the compiler spits out link errors in a rather rudimentary way, a Link Checker as part of the HAT could be a big helper! - Topic-IDs + Context-IDs. You will link your WinDev program to the Help file mainly by using a Topic-ID or a Context-ID. Topic-IDs are numeric, Context-IDs are text - both can call up a distinctive Help page, only Context-IDs can call an Anchor as well. W-Language offers the WHelp-command, which does both:WHelp(“HelpFileName.CHM”, Topic-ID) or WHelp(“HelpFileName.CHM”,”Context-ID”). - Not all HATs will let you see Topic-IDs and Context-IDs painlessly because some HATs are made for producing Help for Visual Studio or Java with rather different paradigms to WinDev. Find the place where you can see and change those parameters! Think twice about purchasing a HAT which makes seeing this type of information hard. Remember that you have to populate all of the windows of your application with Help buttons and you have to insert the proper reference. If looking up and inserting a single one takes a minute, you will have a bad time inserting let’s say 600 IDs. - The Topic-IDs of a Help file are organized in an hierarchical structure. You should be able to easily move any Help page from one place to another within the file. Best are those with 4 arrow buttons which let you move a Topic up / down or left / right. Do not accept anything less! - Compile to CHM. After building the Help you have to ‘compile’ it into a CHM-file. All HATs which produce CHM rely on Microsoft HTML Help 1.4 SDK. You cannot ‘make’ your CHM-file without having installed the SDK before! The SDK is rather ‘old’, its last revision (1.32) is from 2005, there’s no such thing as 1.4 though it’s named that way! Theoretically, the Microsoft HTML Help SDK is sufficient to make Help files in CHM format. There’s even a free open source product named Sandcastle from Microsoft, which supports making Help files. - Though one can circumvent this in various ways, I recommend that you purchase a HAT that outputs your work as a CHM-file, as a web-publishable HTML page collection and as an RTF-file. You can convert the RTF to PDF any time using a free printer driver (e.g. PDF Creator ). There are other converters available on the web which make HTML and RTF from the compiled CHM-file. - Recommended: each file type (CHM, RTF, HTML) should have its own set of settings, separated from the others. You should be able to define two places for each file type where to store the generated file, one on a subdir of the HAT and one e.g. in the exe-.directory of the related project etc. My collection of links in regards to Help Authoring: |
|
|
