Delphi Components That I Use In Helpinator

Unfortunately Delphi community is very quiet nowadays, the most loud voices are the voices of criticism, and authors of excellent components do not get the praise that they deserve. In this post I will try to give the proper credit to components that I use in Helpinator.

TRichView (commercial) – an excellent rich editor component. Comes with a set of actions, that you can use to create a rich editor with just a few lines of code. There are also add-on components for XML input/output, a bunch of spellchecker integrations and etc. The product forum contains answers to almost all questions possible and the author is very responsive to requests.

NextGrid (commercial) – a neat grid component that I like a lot. Not overbloated with features like other grid components from large vendors, just does what it has to do for the money. Has “grid” and “slide” layouts, with the latter each line is like a card. There are also specialized column types, like for showing images, HTML and etc.

SimpleGraph (free) – a killer free component from Kambiz R. Khojasteh that allows to create a diagram editor. Very easy to use like other projects of Kambiz, the code itself is pure genius.

PrintPreview (free) – another great free component from Kambiz that allows to create custom print previews.

JVCL & JCL (free) – actually needs no introduction, a fundamental work of Delphi community, covering all aspects of app development, that will live as long as Delphi lives on.

SynPDF and SynGDIPlus (free) – another work of coding genius, Arnaud Bouchez, that did an unimaginable amount of work with mORMot and infrastructure around it. Seriously, if there’s a Hall of Fame for Delphi devs, Arnaud should lead it, along with Kambiz and Angus Johnson.

Why I like what I created and hopefully you will like it too :) (Part 1).

Helpinator grew naturally out of my own frustration. I was a team lead of a medium sized team and as such I was the one that was responsible for maintaining the project documentation and user manuals. Of course there should be a technical writer for this, but the project was not that large, with a limited budget, and historically team leads were the only ones who knew all the business process inside out and how they were implemented in the system.

Technical writing is hard by itself, especially if you are a programmer by nature. All paperwork and no play make you a dull boy… And then you have to update what was already written and this is when all hell breaks loose. A little change is UI required a massive update of screenshots, that were scattered all over the docs, a time-consuming and exhausting work, that has to be done just to be redone next month all over.

Docs consisted of two parts – context-sensitive help of the CRM/ERP app itself and user manual in PDF. To further complicate things, my predecessor used an unorthodox toolchain of MS Word/MS HTML Help Compiler and some obscure PDF printer. Compiling docs was really time-consuming. He was from the old school soviet “workers” that were raised with soviet corporate culture where you have to be busy all the time to show that you actually earn your paycheck. Optimisations were redundant and people who tried to make things better were called “rationalizers” with negative connotation.

One day I decided that I just can’t carry this weight anymore. This is when Helpinator was born some 11 years ago. It was obvious that I needed another tool and quick search found some help authoring tools that were all cool but didn’t improve anything over doc update process. Over a weekend I put together a simple word-like editor that had a killer feature for me – “Image library” of reusable images and built-in annotation tool for screenshots. In this way all project screenshots were in the library, I also designed a naming system that allowed me to quickly identify images that were about to be updated when something changes in the UI. No more scanning through the topics! My workload reduced by something 50%.

The next moment of enlightment came very soon. A lot of screenshots were duplicates with only callouts differing. This is where I can also save time updating and “cloned images” feature was born. Instead of having a dozen of identical screenshots with defferent callouts explaining different tasks you can have one “donor” image and a dozen of “clones” that inhirit donor screenshot and have their own callouts. And you only need to update one image!

Then I needed code snippets with syntax highlighting and added them to Helpinator pretty in the same way as image library.

One day I was talking to a our ERP/CRM system user of high profile explaining to him how to generate the report that he needed (we had a versatile report generator also created by me). At one moment he stopped me and told me quietly: “I know that your report generator is super cool and feature-rich, but just give me a step-by-step instruction how to get what I want from it”. It struck me like a bolt of lightning. Why waste time writing about features and how one can construct a solution to almost any problem from them, when people in our company are too busy to get accustomed to it, they need solutions. I added “step-by-step guides” feature to Helpinator probably the next day, and the number of tasks explained in a step-by-step manner started to increase exponentially.

That was the moment when midlife crisis came into my life. I got divorced and grew consistently unsatisfied with my job. At that time I wasn’t keen on working remotely (I am now), and there were no interesting job openings in Arkhangelsk (there are still none). I was reading Patrick McKenzie and Peldi from Balsamiq blogs for a while and I think it was them who led me to the business of software. I quit my job and started Helpinator as my primary project.

I can’t say that my life became easy then, it was a tough journey, both in business and personal terms, but this post is already too long, and this story is for the next time.

In case you are still interested, there’s a list of recommended Helpinator blog posts to read: https://www.helpinator.com/blog/2019/09/18/recommended-reading/

14 Days: Day #2 – Putting together a small landing page

1. Domain name.

Nothing fancy here. Nowdays domains are such a widespread merchandise, I beleive you can even buy one along with your hotdog while walking a park on Sunday. I’m a little conservative so I buy domains from NameCheap (no affiliate links here, sorry). They offer an expensive basic hosting plan as well, so I will go for it too. Lucky me, WeirdWrench was available. (Actually I registered that domain slightly beforehand – like a year or so 🙂 Sometimes I register domains that I like for no particular project in mind. So in this case the domain met it’s fate).

2. The landing page

We live in wonderful times when startupship and enterpreneurship is a part of creative culture and the amount of resources you can get (including free ones) is just overwhelming. For the start we do not need an extravagantly designed landing page, we just need it to be mobile-friendly, serve app goal and deliver two call-to-actions (CTAs): download the trial version and subscribe to mailing list of announcements.

You can google for a free landing page template and instantly get a bunch of viable options. Of course, they are not perfect at all, but at the start of your project you do not need to spend time and money and polishing things. You need to deliver the message.

So I ended up with this one: https://startbootstrap.com/previews/small-business/ Needs some tweaks, but it’s OK.

Next we need to set up a mailing list. As I said I’m a little convervative so I prefer MailChimp for this. What I need is an embedded form, but right upon registration they offer only a pop-up form to be created. Finding embedded forms was a kind of tricky, because they lie under “Audience” menu (WTF?) Then you click “Manage audience” next to your audience in the list and select “Signup forms”, then “Embeded”.

Audience – Manage Audience – Signup forms
Embedded forms

The code that MailChimp provides requires styling but I am way too lazy so I googled for a bootstrap template for it: https://gist.github.com/tompec/e32859bf573deef6dc2352bb436b0a88

Just copy URLs and identifiers from your MailChimp-genereated code into it.

Another thing to add to a landing page are social sharing buttons and we will use AddThis buttons, they are easy to install and provide some stats as well. Integration is easy too, it’s just a couple of lines of code.

The same for Google Analytics integration code.

For the image placeholder on the front page I used a brilliant service of free stock images called “Unsplash“. This particular image is by camilo jimenez.

So our basic landing page now looks like this: https://www.weirdwrench.com

14 Days: Day #1 –

From years of software development with Delphi I have a boilerplate app with basic open/save project functionality, integrated LiteHelp help system, basic license management. I will use it as a foundation for WeirdWrench. A few mouse clicks, changing values of a couple of constants and we have an app that we can compile and run.

What we need now is an installer. Thank god (and by “god” I of course mean “Jordan Russell”) we have InnoSetup – a magnificent free tool for creating installers. Let’s open it and create an installer for WeirdWrench, it will take no more than a couple of minutes.

There’s a 3rd party IDE for InnoSetup called InnoIDE, though it’s development has been stopped, the latest version is still a viable product. It has a “wizard” mode that guides you through the most important steps required to create an installer. The wizard does not facilitate all the power of InnoSetup but you can later take on it with the IDE itself.

InnoIDE wizard
The welcome page of the wizard
App name and version
Folder to install it to
Main executable and additional files
Start menu and desktop icons
License file
Output installer params
Directives make your life eazier
Finishing the wizard
Now we can click “Compile” and check the installer

You can download the installer of the compiled proto-app from this link: https://weirdwrench.s3-eu-west-1.amazonaws.com/weirdwrench.zip

Challenge: from idea to the first sale in 14 days with Delphi

Last time I told a bunch of young coders that I am selling a Windows desktop app written in Delphi (it’s Helpinator) my words caused a huge blast of laughter. I was a little angry at first. But then I thought to myself – in times when everything is blockchainy SaaS and React-ive and node.js and docker and kubernetes and a lot of other cool buzzwords, is there still market space for a new desktop app? Obviously it sounds like a challenge and I accepted it right away. So here we go.

I’m going to create a new app with Delphi and march it to the first sale in 14 days.

The idea behind the app is not very revolutionary, in fact it’s just my own itch. I grew tired of WordPress editor and since I already implemented WordPress publishing in Helpinator but for large documentation projects I decided to create a scaled-down editor/blog client tailored at technical article writing that will make it handy to create articles with screenshots, code samples, step-by-step guides and etc, then publish to WordPress, Ghost, Medium, Jekyll, GitHub, Stackoverflow, Wiki and anywhere.

The name for the tool came to me instantly with the idea. I called it Weird Wrench. I like how it sounds, it reflects the technical writing nature of the app, but honestly it was just inspired by the band TOOL.

I do not plan to make long coding marathons, instead I want to finish every day with something actionable that you can play with. So stay tuned.

LiteHelp For Delphi

LiteHelp is a lightweight portable context-sensitive help system for Windows desktop apps. You can read more about it in this post: https://www.dmitripopov.com/introducing-litehelp/

I also created a Delphi unit that allows to integrate LiteHelp into the context-sensitive help of Delphi VCL. It works pretty much the same way HTMLHelpViewer.pas works – just include it into your uses list and provide path to the folder where the help is located using Application.HelpFile. Also you will need to place LiteHelpViewer.exe in the same folder with your main executable. Now Delphi will run LiteHelpViewer.exe and browse to ContextID automatically. You can also locate keywords, execute search and switch languages using commands shown in the Delphi demo included into Delphi distributions that you can download from this link: http://www.helpinator.com/downloads/litehelpdelphi.zip

Here are some code samples

Sample No 1: LiteHelpViewer in your “uses” list:

unit uMain;

interface

uses
  LiteHelpViewer, Winapi.Windows, Winapi.Messages, System.SysUtils,
  System.Variants, System.Classes, Vcl.Graphics,
  Vcl.Controls, Vcl.Forms, Vcl.Dialogs, Vcl.StdCtrls;

type
  TForm1 = class(TForm)

Sample No 2: Setting path to the help folder in the project source:

program LiteHelpViewerDemo;

uses
  SysUtils,
  Vcl.Forms,
  uMain in 'uMain.pas' {Form1};

{$R *.res}

begin
  Application.Initialize;
  Application.MainFormOnTaskbar := True;
  // It's important to provide full path to the folder with LiteHelp files
  Application.HelpFile := IncludeTrailingBackSlash(ExtractFileDir(Application.Exename)) + 'help';
  Application.CreateForm(TForm1, Form1);
  Application.Run;
end.

Sample No3: Executing some important help system commands:

// Open Table of Contents
procedure TForm1.btnOpenTableOfContentsClick(Sender: TObject);
begin
  Application.HelpShowTableOfContents;
end;

// Execute search for a term in edtSearch TEdit
procedure TForm1.btnSearchClick(Sender: TObject);
begin
  IHelpSystem3(Application.HelpSystem).ShowSearch(Trim(edtSearch.Text), Application.HelpFile);
end;

// Locate keyword from edtKeyword TEdit
procedure TForm1.btnGoToKeywordClick(Sender: TObject);
begin
  IHelpSystem3(Application.HelpSystem).ShowIndex(Trim(edtKeyword.Text), Application.HelpFile);
end;

Introducing LiteHelp

LiteHelp is a lightweight non-HTML portable help system for Windows intended to be CHM (HTML Help) replacement, or, at least, alternative. I created it becuase my clients had numerous problems with online help in CHM format. It is long abandoned by Microsoft and ever since continues to grow security issues like a snowball.

I thought to myself: “What the hell, it’s 2019, we don’t need all those fancy HTML bells and whistles anymore. The content is what matters and markdown popularity shows it best”. So I decided to put together somewhat shelved help viewer project and my recent developments in Helpinator and create a help system of my dreams with just enough features and nothing more.

The viewer itself resembles that of HTML Help – a pane with 3 tabs on the left (Table of Contents, Index, Search) and content display area at the right. The only question was what component to use for content rendering but actually it was not much of a question since my code base is heavily dependent on excellent TRichView component from Sergei Tkachenko.

OK, yes, we do not need all that versatality, but we still need some cool things to let our users understand things we talk about faster. If you take a look at modern technical writing it’s not mostly about writing but about structured authoring. Specilized content items are what matters now, and I decided to follow that approach too. Helpinator was based on this approach from the start and in recent versions the number of content items even increased. So far we have:

  • Regular text items with basic formatting – nothing fancy here
  • Tables – OK, everybody need them
  • Figures – this is not just a picture, but a picture with a title and formatted in the output accordingly
  • Asides/admonitions – that colored paragraphs with title and icons intended to bring reader’s attention to.
  • Code samples – need to have syntax highlight
  • Step-by-step guides – not very common item, but it built into Helpinator for a long time already. Also DITA has a similar element.
  • Videos – both embeddable (Youtube/Vimeo) and local
  • FAQs. Though FAQs can be just plain formatted text it’s more convinient to render them as collapsible sections if the output format supports such dynamics.
  • Quizzes. Not that all necessary element, but learning assessment is important part of technical documentation nowdays.
  • Glossary of terms used in documentation.

I managed to implement them all in LiteHelp, so, yes, it’s a very cool help system.

Another feature to be noted is language support. LiteHelp format allows to store all content in one project, and it is possible to switch languages both programmatically and manually by user actions.

The viewer itself is a portable Windows executable with relatively (sic!) small footprint. I has a sort of API available via Windows messaging system, it allows to execute the following commands:

  • Open table of contents (default topic)
  • Open a topic with specified context ID
  • Open keyword index tab and locate a keyword
  • Open search tab and execute search
  • Select language

You can find more detailed description of methods in the readme file in the zip file of viewer.

Download the viewer: https://www.helpinator.com/downloads/litehelp.zip

Download sample: http://www.helpinator.com/downloads/litehelpsample.zip

Delphi help system integration: http://www.helpinator.com/downloads/litehelpdelphi.zip

A small GIF (created with GIFSteps) depicting LiteHelp features:

LiteHelp Features Overview

7 Countries My Most Notable Customers Come From

A long time ago (in a galaxy far far away) I started my own microISV business selling user manual writing tool named Helpinator. Initially I thought that doing business online was quite easy, but it proved to be wrong for many reasons. One of them is that culturual differences affect your business communications. I am a cosmopolite, but with time I started to divide customers into “good”, “bad” or “neutral” depending on the country of origin. I know I can’t call myself cosmopolite while doing it, but it is what it is 🙂

Here they are, 7 to 1, worst to best. Of course my experience is not limited to just 7 countries, these are the most notable ones.

7. China

Surprisingly chinese customers are demanding as hell. Every time I get a support or presales question from China I always feel like that order made me a slave. No matter it was with a serious discount. At some point I even thought to block all sales from China. I’m not very familiar with Chinese culture but I belive there must be some explanation to this. For example, the size of population is so tremendous that support lines of pure Chinese products are overloaded and to get your request fullfield you need to be offensive right from the start or the person on the other end of the line would just ignore you.


Well, it’s not all that completely bad. Once there was a funny case. Bugtracker reported that there were 100+ bug reports overnight. I was surprised, Helpinator was in stable condition by then, there were no serious updates. All reports were from one person, from China. He got a cracked version that was cracked improperly and caused an error after new project was created. And he clicked “Report” every funking time he got that error!!!

6. India

Customers from India are clearly polarized. They are extremely intelligent or extremely dull. Nothing in between. And there are no chances to know who you deal with beforehand 🙂 Thanks to “extremely dull” clients India holds it’s 6th place, I’ve had a really hard time with them, but extremely intelligent ones were a REAL pleasure to deal with. I belive it has something to do with Indian caste system, that severly affects cultural and educational level of a person, though I’m not sure about it.

5. Brazil

Brazilians do not bring in much money but they find bugs that no one can find. Sometimes they use Helpinator in such bizarre ways I could not even think of. But somehow it makes me feel related to them 🙂 And they almost always write me in Portuguese! I like this language (for example “developer” is “desenvolvedor”, sounds like a conquistador wielding a disintegrator gun :), but Google Translate sometimes fail at it miserably.

4. USA

Nothing personal, just business. We need this and that, we will pay N. No trickery or fakes, but nothing warm as well. Do what you have to do, or get out. It’s not that I dislike this approach, but certainly it’s not my favorite.
And also there’s one interesting notion about customers from USA – they are completely sure that the whole planet lives by american rules. No, without any aggression, like “Do what I told you to do”, no. Just because they truly believe, from the depth of the heart, that american way is the best possible choice. But from here I will slide into politics, and I don’t want to do that.

3. Canada

When I was a schoolboy, our Russian textbooks treated USA and Canada as it was the same country, geographically and socially. But in business terms USA and Canada are COMPLETELY different. It’s like to compare a small family restaurant to McDonalds. In a family restaurant you are treated like a family member, at a personal level, while McDonalds is faceless and cold, even if they meet you with a faked smile. That makes a huge difference to me, customers from Canada treat me like I own a family restaurant in their neighbourhood, and they visit me every Sunday, not to just eat but also to talk things over. Maybe that’s why Canadians prefer to deal with what they believe to be a small business (which I have), while Americans prefer large corporations.

2. Netherlands

When it comes to business, customers from Netherlands break all movie stereotypes associated with this contry. At times I even think “the business” itself was invented in Netherlands 🙂 (historically it’s not really untrue). Calm, focused people with clear tasks and plans. No rush, no worry, just steady progress. Thank you, guys, for being pillars of my business.

1. Australia and New Zealand

Oh my god, I LOVE Australians and New Zealanders!!! (or should I say Kiwis?). Always polite and gentle, with really smart and thoughtful suggestions, always ready to help. Never pinch me if a bug requires a long time to fix. And not a single offensive word, even if I funk things up.
Their sense of humour is just perfect, minimalistic and polished. A good joke always makes things much simpler 🙂
With each day I think more and more about relocating to New Zealand. It seems to me that the day for this is close, as Russia keeps on turning into North Korea.

Well, this list is just my personal point of view, I do not pretend to be The Great Source of Online Business Wisdom 🙂
May be your experience is different?