1. Overview

tome.host is a SaaS ("software as a service") designed to simplify the process of creating and maintaining technical manuals, user guides and other structured documentation.

 

Within our system, we call these documents 'tomes'.

 

Unlike traditional content management systems, data in a tome is structured in sections, which can be nested to any number of levels, rather than pages. This makes the data far more flexible, so very specific content can be pulled out for integrated context-sensitive help.

 

Multiple authors can collaborate on tomes, with a permissions system preventing multiple users from overwriting each other's work.

 

Selected changes, or all changes, can be published to the public version with a couple of clicks.

 

The simplicity of the system and collaboration features mean that developers can work on documentation for features concurrently with coding them, reducing the time and cost required for finished documentation to support a software release.

2. Introduction

2.1. Platform

tome.host is essentially software which runs on the web. This means it can be used by anyone with access to a modern web browser (Chrome, Edge, Firefox, Safari, IE 10+). It's responsive, which means that the page layout will reformat on smaller screens like mobile phones or tablets, to make it easier to use.

 

SaaS requires no special hardware, software, infrastructure or IT expertise - all of these are handled by the platform subscription.

2.2. Advantages over conventional documentation

Most organizations still deploy documentation in paper versions, or electronic files like Word documents or PDFs.

tome.host has a number of advantages over these more traditional methods:

  • up-to-date - user always sees the latest published information unlike paper or PDFs and Word docs, where users can retain old versions and may be unaware of updates

  • simplicity - the system takes care of the numbering and formatting, so users can concentrate on the content

  • speed - small edits can be made and published in seconds

  • multi-user - teams can work simultaneously from multiple locations, with source-control style permissions stopping users from overwriting each others' work

  • process - a variety of user-roles allows more formal processes to be put in place for publication, with some authors able to create and edit content, but not publish. Editors can be appointed to proof-read, revise and publish content.

  • usability - direct web links to any heading at any level, layout reformats for optimum usage on mobile and tablet devices

  • embedding content - we provide a simple way to embed help popup windows within your own web applications that target the specific section or subsection you want, saving users valuable time as they can pull up the information they need with a single click and stay within your web application or panel

For organizations that already put documentation online using a CMS (content management system) or templating systems, tome.host provides other benefits:

  • granularity and structure - the ability to nest content several levels deep and easily reorganize sections as the documentation develops

  • fixed URLs - pages accessed via links which remain constant even when headings are moved or renamed

  • embed help content into web back end - we provide simple tools to let you integrate tome.host content directly into your web admin panels via resizable, non-modal popups

  • no special markup - no HTML or wiki type notation is required, anyone who can write an email or use a word processor can create tome.host content

2.3. Basic concept

tome.host has three sets of content - draft, public and archive.

 

Content is created in the draft area, and when sections are ready, they can be selected and published. They will then appear on the public version. The draft screen has a grey background.

 

Only logged in users with permissions can see the draft version of content.

 

The public view has a white background. It can be seen by the public without logging in. Logged in users can switch between the published and draft content using the tabs to the top right.

Above: The published / draft tabs

Whenever new content is published, any existing content which is to be replaced will be moved to the archive. At present this cannot be viewed or accessed, but in future there will be methods available to view the history of changes, view content snapshots by date and restore content (rollback).

2.4. Cost

At present, tome.host is free. In future, we will add additional features which will be available under paid plans too, but will always retain a free, entry-level service. We will also provide paid plans for free to verifiable open-source projects. Contact us for details.

3. Registration

To create or contribute content to a tome, you must have a user account. You can sign up from tome.host for an account. Alternatively, if someone invites you to contribute to a tome, you will be sent a link that will allow you to create an account and join a tome.

Above: Registration requires the bare minimum information

3.1. Confirmations

You must confirm your account after registering by clicking on the link you'll receive by email. This is to ensure that your email address is correct, and belongs to you.

3.2. Sending invites

You can send invites to colleagues or other people that you want to contribute to a tome that you're a member of. If they don't have an account on tome.host already, they will be sent a link that will guide them to set up an account and then map them as a user of the tome. If they already have an account on tome.host then clicking the link in the mail will link their account to the new tome so they'll have full access to it.

3.3. Managing users

If you view 'My Tomes', each tome has a 'User Management' button. Clicking this brings up a page where you can invite new users, or edit/remove existing users. You can also resend invites to users who may not have received the first email for whatever reason.

Above: The user management page

3.3.1. User Types

There are four types of users:

 

  • Admin - Admins can do everything, they manage the tome, and they can even publish other users' work or unlock content locked by other users

  • Editor - can add/edit content and publish

  • Contributor - can add/edit content but can't publish ( an Editor/Admin should review the content and then publish)

  • Read-Only - read-only user; these can access and view private tomes, but cannot add/edit content.

3.4. Password reset

Passwords in the database are salted and hashed, meaning that we have no way to recover your password if you forget it. However, there is a reset mechanism that will send and email with a temporary link that can be used to reset the password.

3.5. Email address changes

At present there is no mechanism to change the email address of an account. Since all emails are verified (to ensure you cannot sign up with a fake email address, or an address that does not belong to you), the procedure for this will require you to contact tome.host support to request a change.

4. Creating and Managing Tomes

4.1. What is a tome?

A tome is defined in the dictionary as "a book, especially a large, heavy, scholarly one."

 

We use the term "tome" to refer to a named container of content, consisting of nested headings, and the various text, image and other content under them.

 

Typically you would create a tome for a particular product or service, to hold instructions or other technical information.

4.2. Creating a tome

To create a tome, go to the "My Tomes" page and click the "New Tome" button.

 

Tome names must be between 4 and 100 characters long, and may contain only upper or lowercase letters, numbers, or dashes.

 

The name you choose will form the address for the tome, for example a tome named "userguide", has the address:

https://userguide.tome.host

 

(the limitation on the characters that tome names can contain is because the tome name is used as the subdomain of the tome address)

 

Because the tome name is used in URLs, you should ensure that it is something that is broadly descriptive or relevant to the content.

 

You can change a tome name later, as long as the new name you want is not already taken. However, it is strongly advised not to do this once a tome is established, as existing links in search engines, forums and so on to your tome will no longer work. It makes sense to think carefully about your tome name and get it right first time.

4.3. Importing a tome

You can import a DocBook XML document to create a new tome. Because tome.host can also export a tome as DocBook XML, you can use this to clone a tome and create a new tome based on the original. To start the process, click the 'import' button at the top of the 'My Tomes' page, name your new tome, and browse to select the file.

Some DocBook XML files exported from third-party applications may not be recreated in their entirety within tome.host, depending on what features and types of sections they contain.

4.4. Opening a tome for editing

In the listings within "My Tomes", click on the name of the tome to view that tome.

4.5. Managing tomes

Above: The tome management page in the admin area

Go to "My Tomes" to list your tomes. Admins of a tome will see a full set of options, whereas contributors and editors can only view/edit tome content.

 

Deleted tomes will display on the system and can be undeleted for a period of a week or so, before they will be cleaned up permanently.

5. Authoring Content

5.1. Starting off

Once you've clicked though to start working on your new blank tome, you should see an instruction to right-click on the root of the tome in order to add your first heading.

 

Once you have added a heading, you will see this on the screen in the main area. You will notice that as soon as you click off the text area, the content saves. You don't need to manually save as you go, any changes to text or headings or other content is automatically saved when you click elsewhere.

5.2. Heading content

5.2.1. Content block types

Currently we support:

 

  • Text
  • Warning text (text with warning sign and red colouring)
  • Info text (text with info sign and orange colouring)
  • Images (with optional caption)
  • Code (SQL, HTML, C#, php, etc.)
  • Video (embed videos)
  • File download

5.2.1.1. Examples

5.2.1.1.1. Text

Just regular text

5.2.1.1.2. Warning Text

This is a warning!  

5.2.1.1.3. Info Text

This is a piece of info!

5.2.1.1.4. Images

Above: This is a Test Image!
5.2.1.1.5. Code

<html>
 <header>
  <title>Just a simple example</title>
 </header>
 <body>
  Hello world
</body>
</html>
   
5.2.1.1.6. Video

Video Content:

This video is available at: https://www.y

Just post the embed text in a Video Tag.


Example:

<iframe width="560" height="315"
src="https://www.youtube.com/embed/2MpUj-Aua48"
frameborder="0" allowfullscreen></iframe>
5.2.1.1.7. File download

Downloadable Content: "This is a sample file download block"

This download is available at: https://tome.host:443/Downloads/2035__fs_1502134401_10170.zip/

5.3. Organizing a tome

Usually the newly content is added at the bottom of the heading, although tome.host supports ordering headings and their contents, using different methods though:

 

  • Headings - To order headings you just need to drag and drop the headings on the left sidebar treeview menu. You can move a heading inside another heading, or move it somewhere else within the hierarchy.
  • Contents - Every content section (text, image, code, ...) has a menu on the left side represented by an arrow, just click on it and you should see the ordering options (Move up/Move down).

Moving content will check out the section, and the change won't be visible to the public until you publish it.

5.4. Cross references

Cross references are internal links within a tome to other sections of the tome.

5.4.1. Creating a cross reference

You can create a cross reference from within a text content box, a warning or an information block. Simply type "@" followed by either the text from the heading you wish to link to, or its section number. A menu will appear with sections that match as you type, and you can click to choose. This will format a link which will include by the section number and the heading text.

5.4.2. Behaviour of cross references

Cross references point to the ID of a particular heading, and so are independent of both the text or the section number used to create them, and that they display. If the section number later changes (because for example, a new section is inserted before it), this should be reflected in the visible text on the cross reference. Similarly, if the text of the heading is changed later, the text of any cross references will immediately be updated.

 

Here is a sample cross reference: @4.2. Creating a tome‍ .

 

Cross references can go directly to any level, for example the third level: @3.3.1. User Types‍ .

5.5. Multiple users and permissions

Many documentation projects require that authors who might be in different departments, working on different features or even based in different locations can collaborate on a single tome.

 

To ensure that multiple users don't interfere with what others are working on, tome employs a permissions system that will be familiar to computer programmers who use source control to allow multiple users to collaborate on software development.

5.5.1. Types of user

5.5.1.1. Administrators

Administrators have full permissions on the system. They can create/edit content, publish content and manage users. They can also unlock or publish content that is checked out to another user.

5.5.1.2. Editors

Editors can create/edit content and publish content. They cannot unlock content checked out to others, and they cannot invite users to a tome or otherwise manage users.

5.5.1.3. Contributors

Contributors can edit/create content, but they cannot publish it. Once they have completed their work, they should unlock it so that an editor can check and publish it.

5.5.1.4. Read-only user

On private tomes (paid accounts only), only users of a tome can view its content - the tome is not visible publicly. The read-only user provides access to view private tomes, but has no ability to edit/create content or make any other changes to the tome.

5.5.2. Checking out content

When a user edits any heading or content within a section, or moves a section, that section will be checked out to them. This is signified in the left hand menu with a green tick.

Above: Section 5 appears with a green tick indicating it is checked out to the author

If content is checked out to you, other authors will see it appear on their menu with a blue icon. They will not be able to edit or make changes to it. If you hover over content or headings that are checked out to other users, a tool tip will tell you who it is checked out to. This way, you can contact that person if (for example) there are urgent changes you need to make to it.

Above: Section 9 here is checked out to the author 'Paul'. It is locked to him and cannot be edited by other users.

5.5.3. Unlocking content

Publishing content automatically unlocks it; other authors will be free to make changes to that section (which will lock it to them).

 

Sometimes, you may not want to publish a section, but might want to unlock it so that another author can work on it. In this case, select the section in the left hand menu and use the 'Unlock' button.

 

The content will remain green (indicating it is not yet published, and is different to the live version), but the icon will revert to the document one.

Above: Unlocked but unpublished sections show with the regular doc icon, but in green

5.6. Publishing content

To publish content, check the sections you wish to publish in the left hand treeview menu, and then click the 'publish' button. Click through the warning popup to confirm.

 

Once sections are published, the icon changes to a grey document again, indicating the item is neither checked out nor pending publication.

 

You don't need to publish all pending sections. If one section is ready before the others, you can publish it when ready and do the others later.

6. Embedding Content into Web Sites

If you have a web control panels on your SaaS product or web software, embedding help can make access to documentation quicker and simpler for the user, and significantly reduces your technical support demands. tome.host has built in tools to generate the code you need.

6.1. Adding the tomehost CSS and Javascript library

You need to link to our javascript library, and also the CSS. It's best to use the ones on our site, as these will be updated as required. You will need the following code added to the HEAD section of your pages.

<link rel='stylesheet' type='text/css' href='https://tome.host:443/bundles/embed-css'>
<script src='https://tome.host:443/bundles/embed-js'></script>

6.2. Getting the link code

Navigate to any heading in the PUBLISHED version. When you hover over it, three grey icons appear to the right. Click the last of these.

Above: The "embed" icon appears when you hover on a heading in the PUBLISHED version

A popup appears which contains the code from @6.1. Adding the tomehost CSS and Javascript library‍ above, and below that, the text for the link. Copy and paste this link text to your page.

Above: The embed popup contains all the information needed to embed tomehost links

You should see the link appear as a small circle with a question mark within it. Clicking this should launch the embedded help popup, and open it to the section where you generated the link.