TomeHost: A specialist user-guide documentation system

Background

TomeHost is a SaaS platform for creating comprehensive online documentation for user manuals, developer guides, and other technical products and services. It was built with ASP.NET MVC and a MS SQL Server back end.

Brief

TomeHost needed to be easy to use, but powerful enough to handle vast multi-level documents for complex software, plant machinery and other technical applications with automatic decimal numbering. Multiple authors needed to be able to collaborate simultaneously, with the ability to prepare content and select when and how to publish. The documentation needed to work well on a variety of platforms, and be easily embedded within other online applications built with any technology.

The solution

We built the system with ASP.NET MVC, Jquery and MS SQL Server. There is a separate administration application for the system which was built in ASP.NET Web Forms.

The user interface for creating content is WYSIWYG, so no special markup is required. There are two tabs "published" and "draft". The published tab shows the present content that is live for the public, and the draft is the version that is being worked on. In this way, content can be developed, over several chapters, and then published in one go when ready, or one section at a time, as desired.

The structured data format allows any section or subsection to be dragged and dropped into a new location, in any part of the document.

With multiple authors involved, there is the potential to overwrite content that others have been working on. TomeHost prevents this with a source-control approach; as soon as a user makes a change to content, the section gets locked out to them (shown with a green ticket) and others can see the current state, but cannot edit or delete that item. Sections checked out to other users show with blue icons. When content is published, the locks are automatically removed.

There are multiple different section types that can be created. Each section must have a heading (which will appear as a subheading if the section is not at the top level), but under that, text, code, images, video, file downloads, warnings and notices can be added.

Because of the way TomeHost data is structured, it is possible to access any section or subsection directly, and see only the content under that. This makes it easier for support staff to direct users to relevant sections, rather than directing them to a large page where they have to search for the relevant part.

TomeHost content can also be embedded within any web application using the provided embedding code. This calls up any link in a resizable non-modal window that stays visibile on top as you perform actions on the page. It can be dragged around and resized to ensure it does not obscure fields the user needs to access. Embedding support content directly in panels, on the actual page where a user needs help, creates a far easier user experience than flipping backwards and forwards between different browser tabs.

A QR code can be copied from any section or subsection to provide direct access to relevant content via a mobile device. In this way, user documentation for a complex vehicle or plant machinery can have QR code links to the specific relevant section places in different parts of the machine, rather than leaving the user to lookup and find the right part of the documentation.

Conclusion

TomeHost enables teams to work together on creating comprehensive documentation. The load can be spread, and the WYSIWYG editor means no special skills or mark-up is required. Companies can maintain up-to-date documentation without the proliferation of out-of-date PDFs throughout the support chain. The decimal numbering system is also well suited to legal documents like contracts, especially when multiple authors need to collaborate from separate locations.