An easy to understand manual for how to use the features of ScribeHub.

Last updated

Attachments
    Loading...

ScribeHub User Manual

Introduction

This manual was written in ScribeHub to describe the features and tools of ScribeHub. Meta! Scribehub is a collaboration tool to help authors, reviewers, auditors and end-users of policies, standards or any important document follow a transparent high-quality process.

The Need

Documents are the media with which humans govern, practice law, standardize and push the boundaries of our collective knowledge. You would think then, that our tools around collaboratively writing and reviewing documents would be well established and robust. The reality is that most collaborative documentation projects are not following a strict or even established process.

The most common collaborative documentation process is a non-process - a mix of offline word editors, email and meetings. If there is an established process, it likely changes based on who is leading the project. Critically important processes such as review can create a mess of non-standardized feedback formats. Standardizing and implementing changes based on this review typically falls on one person, creating far too much work all at once. Or worse - you don't get any feedback at all because your reviewers have no motivation. Reviewers who care deeply about the nuances of a standard may find their comments vanish into ether with no solution. A transparent and auditable cyclical process of review and authorship is needed.

The authorship side is often skewed as well. Some of the most valuable contributors may be volunteers and some of the least valuable contributors may be those being paid the most. This imbalance largely goes unrecognized - once the document is published, authorship is reduced to just a list of names. Reviewers who were responsible for raising the quality of the document significantly are often completely unrecognized. A platform which both records and recognizes the work of both authors and reviewers is needed.

Read on to see how ScribeHub's features solve these problems.

Features

ScribeHub has all the tools you need to write, review and publish documents. What sets ScribeHub apart from other apps is how these tools help you in the process of auditing, quality assurance and engagement, providing a satisfactory resolution to all stakeholders.

Users

Users in multiple workspaces can switch workspaces using the drop-down in the top left.

ScribeHub has two kinds of users: Members and Collaborators. Users can be members of several workspaces. If a user is in multiple workspaces, they can change their current workspace with the drop-down in the top left.

Members are invited to a workspace and have access to all documents within that workspace.

Collaborators are invited to a document and have access only to documents that they are invited to. Collaborators can be invited to multiple documents at separate role levels.

 

 

Invitations

Multiple users can be invited by a list of emails separated by commas. All users entered will be invited at the role level you select. To invite users at different role levels, invite one role group at a time.

Invited users will have 2 weeks to accept their invitation before it expires. Members and Collaborators can have their invitations resent from the Members (Workspace > Members) and Collaborators (Workspace > Collaborators) pages. Users with an expired invitation can also request a fresh email by clicking “Resend confirmation instructions?” on the login page.

Roles

There are 4 role levels. Admins, Managers, Authors and Reviewers. You can have unlimited reviewers for free. Members can be any role while collaborators can be any role level up to Manager. The abilities of each role level are explained on the invitation page for members and collaborators and below.

Ability Admin Manager Author Reviewer
View/export all documents in account Yes Yes Yes Yes
Create comments Yes Yes Yes Yes
Create/import/edit documents Yes Yes Yes No
Add/remove related documents and attachments Yes Yes Yes No
Close/assign/label comments Yes Yes Yes No
Edit others' comments Yes Yes No No
Edit labels Yes Yes No No
Change document settings Yes Yes No No
Invite/change roles of collaborators Yes Yes No No
Invite/change roles of members Yes No No No

You can invite Members by navigating to Workspace > Members > Invite.

You can invite collaborators by navigating to Documents > [Example Document Name] > Settings > Collaborators > Invite.

Document Import

ScribeHub can import from Microsoft Word (.doc and .docx), Open Document (.odt), Markdown (.md) and HTML (.htm and .html). We cannot import from PDF because PDF is not a document format - it's a layout format designed for publishing and printing.

You can browse and select one or more documents as well as drag and drop multiple documents to import. This will upload the document files and a background process will convert and process your documents to our native format. There is a 50MB upload limit on all attachments, including documents for import.

Importing a document performs a few manipulations which bring it inline with the expectations of our editor. It will create unique IDs for any headers which aids in the automatic generation of the outline / table of contents. It will wrap any images in a <figure> element which sets reasonable width defaults for styling and allows for figure captioning.

Known Issues with Importing

With any change in format, there are assumptions which may not lead to ideal results. 

  • Headers inside of list elements (<ul> or <ol>) are not considered valid headers according to our Outline feature. It's best if all headers are block level elements: no parent element except the document root.
  • Blockquotes in MS Word are sometimes interpreted as blockquotes inside of an <ol> element.
  • Word drawings are not natively supported by our editor, but our importer will convert it to a PNG.
  • TeX formatted equations are now supported. If you have a document where equations imported poorly, please contact support@scribehub.com.
  • Tables with merged cells are not supported. Table cell background colours are not yet supported. Tables containing tables are not supported by the importer, but are supported by our editor.
  • Citations support is unreliable. Your citations may lose their anchor IDs and thus break their context references.

Document Editing

You should be as comfortable editing in ScribeHub as you are in any other application. The editor supports collaborative simultaneous authoring, drag and drop and copy and paste from any document format and will automatically handle any images embedded or referenced in that content.

Collaborative Editing

ScribeHub supports collaborative editing. Many users can edit the same document at the same time. You will see avatars and names of users who are actively editing under the "Active editors" sidebar to the right the document. The editor will assign a unique colour to every editor and display where their cursor is to other editors.

In the event that an author has an unreliable connection to the editor service and continues editing, the editor service will automatically resolve content conflicts when the connection is reestablished. In the event that the browser is closed or crashes, go back to the edit page for a document and your latest content will be present. It is unlikely you would need to rely on this however due to our autosave feature.

Currently active editors appear on the right. Their cursors appear in the document. Mouse-over to see their name on their cursor.

Autosave

This dot indicates the save status

The document and notes editors have the autosave feature enabled. This will appear as a green dot in the upper right of the document. While typing, it will appear yellow to indicate that there are unsaved changes. Moments after you finish typing, autosave will attempt to save the document. If that was successful, the indicator will be green again. If there was an error, it will appear red. The most likely cause for an error is a network issue such as a bad client connection.

The editor for comments and replies does not have autosave enabled. If you write in these editors and attempt to leave the page, you will see an unsaved changes notice.

Just follow the instructions to remedy the situation of unsaved changes.

Between Collaborative Editing, Autosave and the unsaved changes dialogue, you should never encounter a situation where you lose work.

Automated Outline

The outline on the left of a document is automatically generated in the background when a document is updated. After updating a document it may take a moment to reload the updated outline and document. An outline which updates as you type is on our product roadmap.

The outline is hierarchical and will open subsections as you scroll. There is also a comments count for each section so you can tell where feedback is happening in the document.

The outline will open subsections and highlight the current section as you scroll.

You can use the filter at the top to narrow down visible sections to those containing what you type. The expand icon will expand all sections and keep them expanded until you click the collapse icon. The double up arrow icon will instantly scroll to the top of the document.

Preferred Editor

Under your user settings, you have a choice of changing your editor from the default of Classic to Distraction-free. Classic shows all the available UI in a persistent toolbar.

The toolbar will scroll with you in the Classic editor. Additional items are available in the three-dot icon menu on the right.

Distraction-free splits the toolbars into block-level and text level actions and hides the toolbars behind a clickable button for a distraction-free experience.

Distraction-free writing in the balloon block editor build of CKEditor 5 WYSIWYG editor.
Try out the distraction-free editor by opting-in on your user settings page.

Related Documents

Related documents are a fast and easy way to associate ScribeHub documents with each other.

Related documents are an easy way to add links between documents in the sidebar. Click the cog icon beside "related documents", filter for the document you want to add and select it. This document will now appear as a link under related documents. You can use this to associate reference, guidance or auditing documents - any relation you want as long as it's a ScribeHub document.

Any author can add related documents as long as the documents being related are in the same Workspace and not in the recycle bin. Added a related document does not change its permissions. If a related document is added to a public document, unauthenticated users will be able to see the link (and the name of the related document), but they will not be able to click through to the related document unless it is also public.

Filtering will narrow relatable documents to those containing what you've typed (by name). If you would like a link to appear in both documents to each other, you'll need to add the appropriate related document in both documents. To remove a related document, just deselect it by clicking the appropriate highlighted related document in the drop-down.

Attachments

Attachments are a super easy way to upload associated materials.

Attachments are an easy way to upload any file you like to a ScribeHub document. Just browse or drag and drop multiple files to upload them. You can use this feature to upload source, guidance or auditing material which is not a ScribeHub document.

A thumbnail will appear for images and a document file icon will appear for recognized formats.

You can edit the name and description of an attachment by clicking the Pencil icon. When finished editing, the disk icon will save. The trash icon will delete the attachment. As usual, you can use filter to filter visible attachments.

The size limit for attachments of all kinds in ScribeHub is 50MB.

 

Notes

Sometimes it's handy to have some extra information for a section. Perhaps authors just need a few bullet points about the requirements for a section, or a section could have reference material. For that, we have the Notes feature.

By default is it disabled and can be enabled on the document Settings page. Once enabled, the document will have a note icon. When a section has a populated Note, it will appear yellow.

The Notes feature allows notes and attachments with a per-section context.

The editor for Notes will autosave your contents - no need to hit a button.

Document Export

ScribeHub can export documents to Microsoft Word (.docx), Open Document (.odt), Markdown (.md), HTML and PDF. Exports automatically include a title page and table of contents.

If a document export is being produced for the first time, it will take some time to generate the file. You'll be brought to your workspaces export page (Documents > Exports) with a notice. Once the file is ready, the page will refresh and the file will be available for download. If a document export is being requested a second time, it is cached and will download immediately.

Document History

ScribeHub has a navigable full history of the document from the time it was created or imported. Autosaves will not generate a new version, but you can publish a new version at anytime with the publish button in the top right of the edit page. You can view all revisions of the document on the history page. The default view is "versions". This displays the whole document as it was at a particular version.

You can change between Version and Changes here.

You can also view the "changes" between two adjacent versions. This difference calculation is intensive, occurs in the background and will be displayed when complete. The result is cached, so subsequent changes views are relatively instant. For very long documents it can take up to 40 seconds to calculate the difference.

On the versions view, you can revert to any version at any time by clicking revert and confirming

As the dialogue mentions, please ensure no one is actively editing the document when you revert it. This could potentially result in lost work.

Document Settings

The document settings page is available under [Document page] > Manage. You must be a manager or admin to see this page and edit the settings. A few simple settings can dramatically change the purpose and interactions of a document.

Public: When enabled, a document will be available to anyone. This includes users without a ScribeHub account. Be totally sure that this is what you want before enabling. Even if only enabled for a short time, it's possible a bot (or user) could collect the contents of the document and store it indefinitely. When disabled, a document will only be visible to members of the workspace or collaborators who have been invited specifically to that document.

Comments: This turns off/on the Comments feature. Disabling will hide the Comments tab and users will no longer be able to view or reply to existing comments.

Editing: This turns off/on the ability to edit the document. Admins will still have the ability to edit. This is useful if you would like a review period where the document doesn't change or if you'd like to temporarily restrict editing to admins only.

Archived: Archiving a document visually marks the document as archived and displays a banner saying who archived it and when. While archived, editing is disabled and comments will be read only. You can unarchive a document at any time. Archiving and Unarchiving will create activity feed items.

Ownership: The person who created a document is marked as the document owner. Currently it is not possible to change who owns the document. The owner of a document does not have any distinct permission abilities - it is only meant to state who is responsible for the document.

Discard document: Discarding a document places it in your workspace Recycle Bin (Workspace > Recycle Bin > Documents). Admins have the ability to restore the document for 60 days or permanently delete the document on the Recycle Bin > Documents page. After that, it's gone for good. While we have database backups, these are securities for catastrophic events. ScribeHub does not offer data recovery as a service. It is a good idea to export a document before discarding or permanently deleting it.

Comments

ScribeHub comments are perhaps a bit more complex than you're used to. Don't worry, it's very easy to create comments! The extra features make it much easier to engage users, to sort through feedback, see how a discussion changes over time and see what the ultimate outcome was. At the resolution of a comment, the thread remains as a record of that comment being raised and resolved. Closed comments can still be discussed and that discussion may lead to the reopening of the comment.

Comments can be created on the new comment page, or via the comment sidebar. It's easier to create multiple comments via the sidebar, and you have the content right there to reference. You can set the section on a new comment by clicking the "+" button beside a header. Opening comments on specific sections keeps the discussion more organized.

1 - Create a generic comment. 2 - Create a comment on a specific section. 3 - Open this sections comments in a new tab.

Comment "unread" feature

If you have not already seen a comment, a blue border will appear beside it to indicate that it's unread. Loading the comment will mark it as read. If someone other that you replies to the comment, it will be marked as unread again.

The blue line on the left indicates that this comment has unread content - either the comment itself or new replies.

Discussion Thread

Comments can be replied to, closed and reopened. As long as the document is not read-only and the comments feature is enabled, comments can be replied to regardless of them being open or closed. Authors can close any comment while reviewers can only close comments they opened themselves.

Comments can be assigned to any user with the author role or higher. This includes both members and collaborators. When a user is assigned, they will receive an instant in-app notification and be subscribed to the comment. See the subscription section for more info about what that means.

When changes happen to the comment assignee and labels, those changes will be recorded in the discussion thread. This produces an audit trail as a timeline which mixes into the discussion.

Changes to the status (open vs closed), assignee and labels are seamlessly recorded into the discussion thread, creating an auditable history for each comment.

The discussion thread updates in real-time. If 2 or more people are the same thread at the same time, it behaves like a chat.

Comment Subscription

Comments can be subscribed to via 4 actions.

  1. The user who created the comment is automatically subscribed.
  2. Any user who replies to the comment is automatically subscribed.
  3. Any user who the comment is assigned to is automatically subscribed.
  4. Any user who clicks the subscribed button is subscribed, obviously.

The reason you're subscribed to a comment is mentioned below the "unsubscribe" button. Clicking unsubscribe will of course unsubscribe you. If you wish to manage all your subscriptions, click the inbox icon in beside your avatar in the top right and select Settings > Comment Subscriptions.

When subscribed to a comment, you will receive an instant in-app notification and an email when the comment is replied to, when the status changes from open to closed, when it is assigned or when the comment is reopened.

Reply-by-email

When subscribed to a comment, replies and changes in status (open or closed) will send you an email. You can reply to this email directly and the application will insert your reply into the thread. You can be a part of the conversation without even having to open a browser or sign in. Convenient!

Some email clients can behave poorly when interacting with reply-by-email. Mail for Windows and Outlook are highly non-standard in how they apply CSS, manipulate markup and fail to wrap the email history in consistent markup or any markup. This makes it very difficult to accommodate - we do what we can to remove email history and sanitize emails from appearing in comment replies. Webmail clients (such as G-Mail) are generally not an issue.

Comment Labels

Comment labels are a means to organize comments within a document. Each document has the default labels of blocked, duplicate, enhancement, fault, invalid and question. You can edit and delete these labels under Manage > Labels.

Every document has default labels which can be edited and deleted.

There is no limit to how many labels a comment can have. Labels can be filtered in search by:

  1. Clicking a label in the index view
  2. Selecting a label in the label filter drop-down
  3. Typing in the search bar - ex. “label:blocked”

These filters can be mixed with any other filter or sort condition.

Comments Export

You can export all comments in a document to CSV in one click. You need to be a Manager or Admin to export comments. This works in conjunction with search - you can export your filtered and sorted comments or export all comments from the export drop-down.

You can export all comments or just search results as a Manager or Admin.

Comments and replies unfortunately lose their HTML formatting as CSV only supports plaintext. The best way to reply to or otherwise interact with Comments is on ScribeHub.

Comments on Historical Sections

As a document changes, sections and their headers may come and go. If a header is deleted from a document it marks the associated section as "historical". Any comments on this historical section will have an icon to indicate this.

The v0 indicates the last version of the document this header was last seen in.

You can always view historical sections via the history tab.

Recycle Bin

Documents and Users are discardable and recoverable. Discarding resources will place them in the Recycle Bin for 60 days. After 60 days, the items are automatically permanently deleted. You can also permanently delete discarded resources yourself by clicking the trash can icon on the Recycle Bin page.

Discarded Members do not have access to the workspace. Members can discard their own workspace account - keep this in mind if you are re-inviting someone. If you re-invite a discarded member and it will automatically "undiscard" their workspace account - no need for them to register again.

When a user is permanently deleted, their contributions to comments and documents will be attributed to "Deleted User". To delete the contributions themselves, the parent document would need to be deleted.

Content contributed by deleted use will be attributed an the anonymous “Deleted User”.

Currently the only way to destroy comments and replies is to destroy the parent document. This is for integrity and auditing purposes.

Public Documents

Marking a document as public allows anyone to read your document. This is effectively a one-click publishing feature.

As an unauthenticated user, the comment buttons have instructions on how to register in order to provide feedback.

Pro Features

The free plan gets you a lot, but the Pro plan gets you everything. The Pro plan is ideal for projects conducting massive feedback, such as public consultation for government public engagement, or for very important documents which require full auditing and engagement metrics.

Engagement [Pro Feature]

Ever wonder what the full reach of your document is? Wonder no more! The engagement page has a collection of helpful graphics and graphs to help you understand how active your workspace is over time, who your most active authors are and which documents are performing best.

See the role and user type breakdown.
See daily activity over time
Make it into the top 3 most active users in a workspace and you can stand proud atop a podium!
Compare the popularity of your documents. Visits are all impressions and user impressions are by authenticated users.

Auditing [Pro Feature]

Almost all actions in a workspace are tracked and available in a searchable index under Workspace > Audit. Admins have the ability to see who did what and when and narrow activities to individual users. Unauthenticated users are also tracked if they are in your workspace (on your subdomain) which allows you to see failed login attempts.

The audit page lets you see who did what and when and to what resource. Almost all actions are tracked, as well as the server's response.

Pricing

We have two plans - Free and Pro. Simple! For the Pro plan, there is the option of monthly or yearly billing. Yearly billing saves you a whopping 30%.

Feature Free Pro
Public documents 1 Unlimited
Private Documents Unlimited Unlimited
Free unlimited reviewers Yes Yes
Import Microsoft Word, Open Office, Markdown and HTML documents Yes Yes
Export documents to Microsoft Word, Open Office, Markdown, HTML and PDF Yes Yes
Full document revision history, changes view and version control Yes Yes
Comments to collect, organize and resolve feedback Yes Yes
Assign-ability, audit trail and reply-by-email for comments Yes Yes
Export comments (all and search results) to CSV Yes Yes
Comprehensive full-text search for Documents, Users, Comments and their replies. Yes Yes
Up to 5 support requests per month No Yes
Engagement statistics. Compare your users and documents to see where value is coming from. No Yes
Audit feature. Searchable audit log for almost all actions in workspace is available to admins. No Yes

Reviewers will always be unlimited and free. This can end up saving you thousands(!) compared with other applications. You're welcome!

We save you money by only charging you for users who are actively using the application. If you invite someone and they don't accept their invitation, you will not be charged for that seat. Users are considered inactive if they haven't signed in for 7 days.

The cost of the workspace fluctuates with accepted invitations and user activity. These fluctuations are charged and rebated relatively instantaneously.

Questions

If this document has not answered a question you have, please open a comment and we'll answer it. We may also document the answer in the contents of this document. Transparency and satisfied stakeholders is what we're all about!