A new help system for our add-on

Last year, we took the first steps towards proper on-line help for our add-on. Before, we had always had documentation in the form of Microsoft Word and PDF files on a network share, but the new system, based on the NAV Help Server, was intended to provide an easy-to-find, uniform, multi-language-enabled, extensible, searchable source of information for both our consultants and end-customers.

The system is starting to take shape

Step by step, the new on-line help, with an initial focus on conceptual topics, is starting to take shape. Our documentation specialist writes the topics in MarkDown – a file format we chose for its shallow learning curve and emphasis on document structure. In addition, MarkDown is a text-based format (as opposed to e.g. Microsoft Word files, which are binary), which enables meaningful version management (e.g. comparing revisions) in TFS. Topic post-processing and conversion from MarkDown to HTML (which is the file format that the NAV Help Server needs) is done as part of the build process.

The problem: full-text search is not working

Everything worked swimmingly, except for the NAV Help Server’s full-text search – it simply would not find any of our topics. No problem in finding the NAV base application help topics, though. Hmmm…

Hmmm...

Maybe our topics are not indexed?

I initially assumed that it was a permissions issue – perhaps the Windows Search indexer did not have the required permissions to index our topics? However, after figuring out how to query Windows’ search index (more or less like this), I could see that our topics were indexed just fine.

Maybe the help server only searches its own folders?

Another possible explanation for not finding our topics was that they lived in a subfolder of the NAV Help Server’s language folder (i.c. en). Maybe the help server only searches its own folders?

As a little experiment, I copied one of our topics to the en folder and searched for a word I knew it contained, but still no luck. This would turn out to be a bit of a red herring, as you can read below.

NAV Help Server’s inner workings

Flash-forward another 30 minutes. By then I had found out two rather essential things about how the NAV Help Server searches the index:

  • It does only search the language folder for the active language (‘active’ being the language referenced in the help server url). However, the reason why copying my add-on topic to the language folder still did not render any results was due to the other thing I found out:

  • From what it finds in the index, the search handler only returns topics that have both a file name (which our topics obviously did) and a title (which – as you may have guessed – they did not).

Conclusion

Pandoc, the tool we use for file conversion between MarkDown and HTML, can use meta information in your MarkDown to add, among other things, a <title> tag to your HTML, but – of course – only if you provide such information. After the summer holiday, that will be the first thing to implement. Also, our documentation build process should copy its output to the language folders of the NAV Help Server, possibly prefixing our topics to differentiate them from the base help and to prevent file name collisions.