Continuing our series of posts on upcoming developments for version 10.2, we will now turn to some functionality entirely outside of the program, namely the documentation. OrcaFlex is an ever growing program, and as it grows, so too does the documentation. For version 10.2, we decided to make a number of significant changes to the documentation, especially in how mathematical formulae are presented.

Over the years, the OrcaFlex documentation has passed through many different formats, and undergone numerous transformations. When I first knew it, over 20 years ago, the documentation existed as a 16 bit RTF based Windows help file (.hlp) and a Lotus Ami Pro document for the printed manual. The sources for these two formats were completely disconnected, so whenever we made changes we had to apply those changes separately to each source, a very error-prone state of affairs. Leaving aside the quality of the content (we will let you judge that), the mechanics of working on the documentation were painful. Just remembering how it used to be back then makes me want to cry, and that’s before I’ve even mentioned our revision control systems of the day!

If we fast forward to today, then things are much improved. Our documentation has a single source, and indeed has done for a very long time. The raw format of the source is HTML and we use a help authoring tool, MadCap Flare, to produce various targets: compiled Windows HTML Help, online Web Help and until recently a printed manual in Word/PDF format.

We recently dropped the printed manual format; version 10.0 was the last version which was accompanied by a printed manual. There were a number of reasons for this. It is quite tricky to author content to be used in both hyperlinked format (online help, web help, etc.) and printed manual format. Hyperlinks don’t map very well to the printed page. Generating the printed manual required some complex Word automation scripts that were quite challenging for us to maintain in the face of new versions of Word. But the single biggest motivation for dropping the printed manual format is that maintaining multiple targets for the documentation constrained us to the lowest common denominator for formatting. By that I mean that we could only ever use formatting, styling, etc. that was available in each of the targets.

The most significant constraint imposed by supporting multiple targets was the presentation of mathematical formulae. We were limited to using standard text with subscript and superscript. This severely limited our ability to present equations in a clear manner. There are a number of tools available for Word that we could have used. And there are a number of tools available for HTML. But trying to find a single tool that works for both was not viable.

Dropping support for the printed manual target means that we can concentrate on the two remaining targets: Windows HTML Help, online Web Help. Whilst Windows HTML Help (.chm) was the trendy new thing when it was first released 20 years ago, Microsoft has long since stopped developing it. This also makes it hard for us to use modern tools to present mathematical formulae. Our solution to that has been to drop the Windows HTML Help target as well, leaving just a single target, online Web Help.

Now, before anyone gets worried that OrcaFlex help will require access to the internet and be delivered in a web browser, that’s not going to happen. What we are doing in version 10.2 is providing a dedicated tool, installed alongside OrcaFlex, that will display the web help content using an embedded web browser. The content is installed with OrcaFlex and is stored locally. We refer to this tool as the Orcina Help Browser. Think of it as a like-for-like replacement of the Windows HTML help viewer. The benefit of doing this is that we can use modern HTML5 and Javascript technology, which is what is needed to layout the formulae.

So far, I’ve spent a lot of time talking about how things are implemented internally. I suspect that is more interesting to us at Orcina than to you users. So, let’s see some screenshots to show you how things are changing. First of all, an example of how maths is presented in the old system. This is from the 10.1 help file:





The formulae are correct, and all the information is here. It is just very hard to read. Given a pencil and paper, nobody would ever write it this way.

And now the same content as it will be presented in the 10.2 help file:





I’m sure you will agree that this is significantly more readable. The magic that makes this possible is the wonderful MathJax project, for which we are very grateful.

As well as improving the appearance of the documentation, we are also taking the opportunity to review the entire content. Given that we need to work through the entire body of documentation revising the layout of formulae, we felt that it would be opportune, at the same time, to review the content more broadly than just the presentation of formulae. The documentation is the work of many different authors, over many years. The content has often been added in incremental fashion as new features are introduced, or as existing features are updated. A consequence of this is that many different stylistic preferences can be found in the content. We are therefore reviewing the content with the intention of imposing a consistent style throughout.

Furthermore, when we do make changes to OrcaFlex, we don’t always find every single section of documentation relating to those changes. It can be very hard to do so because there can be references to a particular part of the program scattered around many different topics. We have found, as we review the documentation, a significant number of topics that contain statements that are now out of date.

Documentation is a very important part of our product. We do take pride in it, and we strive for it to be comprehensive and accurate. This overhaul of the documentation, for version 10.2, is intended to make the help even more helpful!