Authoring tools for startups -- Guest post by Vinish Garg

by Vinish Garg 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. 

---

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.