It's been a very busy period at Simplexable as we work towards release of the new accountd platform. Each time we do a new project, somwhere along the way we discover a new concept that ends up being rolled back into our earlier work. The most recent example of this is a fresh look at the concept of providing “help”.

In our last three major projects, we released them with a live Google Doc which we maintain as a user guide. The document is nicely formatted (courtesy of Google's amazing prowess) and provides extensive background and support in how to use the tool. It's fundamentally flawed however, because you have to open a separate tab and plow through many tens of pages to find the section that describes what you need.

When putting accountd together, we knew that we were going to need a lot of documentation, and this started out as the same type of document, but then we had an idea for a focused help server.

• link the current tool to a help record
• have the help record hold only metadata — no content
• allow a referential system to indicate other related topics
• include internal notes to track the help topic, etc. that are not visible to users

What we developed was a separate help server where the database has only one table:

help=# \d help
                                    Table "public.help"
  Column  |            Type             |                     Modifiers
----------+-----------------------------+---------------------------------------------------
 id       | integer                     | not null default nextval('help_id_seq'::regclass)
 platform | numeric(1,0)                | not null
 title    | text                        | not null
 updated  | timestamp without time zone | not null
 draft    | boolean                     | default true
 related  | character varying(50)       |
 notes    | text                        |
 

platform refers to the service (stockd, servicd, accountd, or topical) where the article applies.

related is a series of related articles listed as id[space]id[space]...[id]

The call to the helpd server is a single page with an article reference. It opens a tab on the user's browser and loads the title from the help table. Then it loads a static HTML stub containing the main content of the help file via a simple (and fast) file read. Then it picks up titles on any IDs present in related, and finally closes out the page

We think this has serious advantages including:

• Use a single (shared) resource to serve help for multiple platforms.
• Setting up a call to the helpfile is as simple as knowing the correct article ID and passing it in the URL.
• We only need one server and a simple interface to maintain hundreds of help records.
• CSS and other formatting issues are centralized on the one server.
• Static HTML is easier to maintain than database stored text.
• The related list is easy to update.

We're going to be migrating the entire help system for stockd and servicd into this structure as soon as possible. It makes more sense to give the user a targeted help file than to ask them to parse 50-80 pages of a Google Doc to get the answers they need. I hope these ideas are useful in your own take on being more helpful.