← All Articles

Technical Documentation is Broken

Khash SajadiKhash Sajadi
Nov 25th 11Updated Jan 24th 19

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 companyand 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?!


Try Cloud 66 for Free, No credit card required