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.
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.
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:
For organizations that already put documentation online using a CMS (content management system) or templating systems, tome.host provides other benefits:
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.
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).
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.
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.
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.
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.
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.
There are four types of users:
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.
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.
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.
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:
(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.
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.
In the listings within "My Tomes", click on the name of the tome to view that tome.
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.
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.
Currently we support:
Just regular text
This is a warning!
This is a piece of info!
<html> <header> <title>Just a simple example</title> </header> <body> Hello world </body> </html>
This video is available at: https://www.y
Just post the embed text in a Video Tag.
<iframe width="560" height="315" src="https://www.youtube.com/embed/2MpUj-Aua48" frameborder="0" allowfullscreen></iframe>
Downloadable Content: "This is a sample file download block"
This download is available at: https://tome.host:443/Downloads/2035__fs_1502134401_10170.zip/
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:
Moving content will check out the section, and the change won't be visible to the public until you publish it.
Cross references are internal links within a tome to other sections of the tome.
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.
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 .
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
<link rel='stylesheet' type='text/css' href='https://tome.host:443/bundles/embed-css'> <script src='https://tome.host:443/bundles/embed-js'></script>
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.
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.