Technical Documentation is Broken

We are very close to the public release of CloudQuartz the job
scheduling and automation engine for the
cloud
. As part of our work we need our
technical documentation to look good and be easy to use.

Thing is, it is not as easy as it sounds.

What do we need?

  • Simple to add and edit documents with lots of code snippets and screenshots.
  • Simple to template so it can integrate well with our website.

See? Only two main requirements! What we need is a way to product
content easily. Google will do a great job in helping people retrieve
it.

So we started looking for a good solution. Here is what we tried:

What did we end up with?

Doing it ourselves. You can see the results in
CloudBlocksdocumentation.

Why?

Well here it is in a nutshell:

Tender App

Tender App is great. It’s simple. Supports Markdown which is the way to do technical documentation and doesn’t try to do everything. But: It’s way too expensive to what it does: \$24 per month for 3 agents and no customization whatsoever is just too much.

Assistly

I like Assistly. We used it in our previous
company
and the support guys liked it. It is
good for aggregating all your support in-streams like email, twitter and
facebook, manages cases and all that. But it’s mostly focused on the
support side of things and not the knowledge base side. Assistly has a
knowledge base, but it doesn’t support Markdown, has a super clunky HTML
editor and image uploader which makes producing documents very
difficult. The customization options are also fairly limited and/or
cumbersome.

Based on my enquires with the company, they are going to support
Makrdown and improve the HTML editor soon but that’s too late for us.

Wordpress Knowledge base templates

Wordpress is the way forward for us. It is extensible and has a large
community while still being way simpler than a full blown CMS like
Drupal.

However, we are not Wordpress experts. To build a knowledge base around
Wordpress, we need to either do it from scratch or get one of the few
existing WP knowledge base templates and make changes to them. The
problem with that is we are constantly iterating our UI and want to keep
the knowledge base with the same look and feel with the rest of the
site. This means we (or an external resource) will be changing the WP
template constantly for sometime which for us is not a viable solution.

So here is what we did

Inspired by High Voltage we wrote a simple Rails controller, used
Maruku to parse our Markdowns and shared our site CSS and templates to get a seamless integration.

I am going to write more about Maruku and RDiscount in a future post,
since we started with RDiscount but switched to Maruku. But for now I
think this is enough!

The moral of the story is

Technical Knowledge base is broken and can have someone fix it with a
cheap SaaS solution. Any takers?!

Khash Sajadi

Khash is the founder and CEO of Cloud 66, a full stack container management as a service. Follow him on @khash

London, San Francisco
Subscribe and get updates

Have feedback? Please get in touch @cloud66 on Twitter.

Everything you need to build, manage and maintain containers in production on your own servers and any cloud

Try Cloud 66 — 14 Days Free Trial, No credit card required