Search results

Authoring tools for startups -- Guest post by Vinish Garg

by Tom Johnson on Dec 11, 2014
categories: technical-writing

The following is a guest post by Vinish Garg, an information architect with a background in technical writing who frequently works with startups. 


Vinish Garg
Vinish Garg shares his thoughts on authoring tools for startups

A discussion on authoring tools invariably leaves the participants with at least one common opinion–they want to see something better in whatever tool they are using. I recall a Wishlist post that Tom wrote a few years back; I am not sure how much we can revise that wish list today. The next common facet of such a discussion is a quiet shared laughter about the tools.

Making a decision on an authoring tool depends on many factors. I often receive messages on LinkedIn with authors seeking my advice on selecting authoring tools. Their questions remind of Decathlon when it opened its first store in Chandigarh. One of my sports enthusiast friends went to the store, and on browsing the aisles, was not sure of what to pick -- the rackets, a club, or the baseball gloves. Not sure what to start, and why.

However, when we talk about startups, the process to select an authoring tool is quite different. Ryan Hoover from @producthunt says that Product Hunt gets 250-300 product submissions a day, and of these, only 50-60 get listed. So startups are really mushrooming, and that is good news.

Documentation for Startups: Approaches and Priorities

In last few years, I have worked with a few startups as a contractor. Either they had just launched a product and were connecting with their first customers, or they were about to launch.

A startup has a different approach to documentation:

  • Priority and Urgency: Customers are their only priority, and so they need minimum content to help guide their first customers.
  • Minimum Viable Content: They often need MVC to begin with; they cannot afford to dedicate exclusive time or resources for documentation. Mark Baker has an excellent post titled In Praise of Short Term Thinking that is quite relevant to startups' documentation strategy.
  • Team, SME: Most often, startup teams are small, and the owner or CTO is our SME.
  • On Board: Startups cannot afford a technical writer on board; they do not plan to hire one either, and they are not sure if they will have ever have a permanent writer on board.
  • Long term Strategy: When I try to learn their long term documentation vision, they are not sure of it (e.g., other deliverables, whether different documents for different users, multiple languages).
  • Budget: Startups are often low on budget (even if funded).

Preferences and Priorities

Before I share my experiences of startups' documentation preferences, let me share a few example startups. Pick a random product from @producthunt. I picked a few randomly, including http://louder.org/, http://knotable.com/#/, https://videolean.com/, https://supportyard.com/, and http://www.spokepoint.com/. The products often have a FAQs page, or a "How It Works" page for basic instructions for their customers. Generally, startups have the following documentation preferences:

  • Deliverables: The online manual is the only deliverable, in one language. They need an authoring platform that they can use themselves, to write if required. They don't have time or resources for XML schemas, or to set up rules and validations, so a case for an XML authoring tool falls flat.
  • Self-authoring: They want a platform that allows them to write themselves. The team starts writing guides (articles) close to the launch. They want a Google Drive Doc, a simple WordPress theme, or help desk KB authoring platform. When they have an author on contract, they prefer to continue it in some cases, by writing quick notes or drafts that authors can take over. No review sheets, and very little back-and-forth. So help authoring tools such as RoboHelp, Flare, and Author-IT do not interest them; and they lack budget to spend on such HATs.
  • Collaborative authoring: They want collaborative authoring to track versions, revisions, and a simple web-based "write-save-review-approve-publish" publishing process. Wikis are an appealing option here.
  • Analytics and metrics: Analytics and metrics are important; they are often interested to see and share Most Popular Topics, Top Rated Topics, Recently Viewed Topics, and so on. A CMS serves this need well.
  • Cloud Based, Hassle Free: They need a tool that does not need any installation, configuration, and troubleshooting. It should be cloud based and affordable.
  • Branding and Styling: They prefer to have control over the branding and styling, with basic theme settings by drag-and-drop interfaces, and CSS tweaks. A CMS shows them a rosy picture here.
  • Integration: They need integrations with help desk systems such as Zendesk, Desk.com, UserVoice, and with online chat services such as Olark.
  • Advanced Search: They need a powerful search feature, possibly powered by AJAX, or by integrations with Algolia.

Other Documentation Factors for Startups

Here are a few other documentation factors with startups:

  • I often advise startups to plan for reusable content chunks so that we could plan for Quick Guides, Admin Guides, or Inline Help in the future.
  • There is no formal process for issue tracking, so integration with tools such as JIRA is a low priority.
  • Startups need an easy way to set up and manage information hierarchy (such as categories of topics, and content chunks if possible).
  • Startups do not have a vocabulary or terminology guide. (With a single writer authoring in one language, consistency is not a concern.)
  • Not many startups need PDF versions such as for Quick Start Guides, but it is a nice to have. A CMS allows publish to PDF; most cloud based services don't.

Authoring Tools: Options

Here's a quick look at a few broad level categories of authoring tools:

  • HATs (RoboHelp, Flare, Author-IT, Help&Manual, and few more)
  • XML Editors (OxygenXML, EasyDITA, Arbortext Editor, and few more)
  • Wikis (Confluence, Wikis)
  • CMS (WordPress, Drupal, and others)
  • FrameMaker (I am not sure where I can list FM above, hence its independent space)
  • CCMS (or custom support services such as by MindTouch?), way out of their budget
  • Cloud based (ScreenSteps, Zendesk, Elev.io, and few more)
  • Quick Simple Site Generators (Jekyll, DocPad, and possibly few more) (Thanks Tom, for pointing these two to me)
  • A variety of scripts and APIs for advanced options such as Agolia for Search, InsetPlus for content reuse, and few more
  • There may be a few quick-fix or custom authoring workflows as Tom described in Using Google Docs and Markdown

Now considering the startups needs and priorities, I can conclude that startups

  • rarely opt for DITA or even XML-authoring environment in a HAT
  • are resistant to HATs for lack of authoring flexibility for the basic learning curve
  • have a strict No to CCMS for cost and learning curve
  • dislike wikis as they lack custom search features and don't scale well to adjust with additional deliverables
  • may not always like Jekyll or DocPad because not many authors can use these (e.g., I saw DocPad, and there is no GUI, I am not sure how we can fetch related topics automatically, and how taxonomy works)

My Experience

I have worked with a few startups for their documentation tasks. A quick recap on my experience:

  • WordPress: I worked with two clients who decided to use WordPress for their documentation. Their corporate website was developed in WordPress and hence they opted for WordPress for their their KB. Their reasoning for choosing WordPress was as follows: (1) They were familiar with the authoring (in spite of its limitations) and (2) They could carry the same branding. For one client who implemented WP, their whole KB was developed in WP. For another, their documentation was developed in a HAT, and they planned to export and publish it to a WP theme.
  • Cloud Based Authoring: I have two clients who are using ZenDesk for KB authoring. I talked about the detailed experience in a few blog posts. I also used HelpIQ and ScreenSteps. Both are just enough to set up basic documentation; each has its own limitations.

So, the Options for Startups

Startups have few options for help authoring:

  • Default KB  themes from open source CMS such as WordPress (see some examples on themeforest)
  • Cloud based authoring tools (I see UserVoice and ZenDesk being used so often)
  • Quick Simple Site generators (given that they provide a GUI, basic customization of content types, and taxonomy support)

Based on my experience, the minimum wishlist for startups' authoring tools is:

  • Collaborative authoring, with reviewing and revisions
  • Snippets for reuse
  • Custom taxonomy
  • Content chunks (such as to import videos from an external source)
  • Role-based access to an authoring environment, and to front-end users
  • Custom branding and styling
  • Custom views to fetch specific set of topics

Do you think that easy and lightweight CMSs or cloud-based authoring tools are a better option for startups?

------------------

About The Author

Vinish Garg is an information architect with a background in technical writing. Vinish takes contracts specifically for startups, for business analysis and product scoping, product design, IA and knowledgebase development. Vinish is co-founder @stocci, and he lives in Chandigarh. You can learn more about him at www.vinishgarg.com.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.