h1

LavaCon2018: Day 1

October 23, 2018

I helped out on the Registration desk this morning. It was a bit of a madhouse, with three of us checking in about 450 people in just on an hour!

By the time I got into the intro and plenary sessions there were no seats left, it was hard to see the screen, and hear the speakers, so I left after Karen McGrane’s keynote.

Some notes from McGrane’s talk:

  • How to create content for any format (including audio only), any device, any screen size, no matter what the ‘next big thing’ is, even for devices not yet created?
  • Still too much reliance on visual styling (as used in books/paper) to create meaning. The web isn’t print — the way people create content has to change.
  • Content ecosystem has to be navigable whatever size device (e.g. watch to stadium screen; digital signage), even if not the primary target device.
  • Need true separation of content from form; presentation-independent content.
  • Content must be readable, browsable, and accessible on any platform/device.

Word and DITA

The first general session I attended was on Microsoft Word and DITA, and featured Doug Corman speaking about the pros and cons of each and how an add-in from SimplyXML could make it easier to general authors to write in a style compatible with DITA (yes, I checked with him afterwards about the add-in’s applicability for editing, and it’s not).

My notes from this session:

DITA positives:

  • XML standard
  • separates content creation and form
  • supports topic-based authoring
  • information typing
  • re-use at many levels
  • open source
  • large global community of practitioners
  • proven for tech pubs
  • flexible (640+ elements)
  • integration with CMSs and modern processes
  • control through a standard architecture

DITA negatives:

  • 640+ elements!
  • transformation costs from Word, XML, PDF
  • XML editors are complicated
  • DITA tools are expensive
  • expertise required for implementation
  • rework/rekeying of DOCX, PDF may be required.

Microsoft Word positives:

  • ubiquitous (at least 1 billion users)
  • does everything
  • has footnote/bibliography capability
  • has review functions such as track changes and comments
  • publishing format flexibility — fonts, templates

Microsoft Word negatives:

  • does everything (flexibility)
  • full DITA functionality is impossible
  • standards, macros can be violated
  • authoring and publishing are tightly integrated

Best of both (ideal world):

  • XML
  • topic-based authoring
  • information typing
  • re-use at many levels
  • open source architecture
  • large global community of practitioners
  • flexible — 640 elements or fewer
  • integration with CMSs and modern processes

SimplyXML has a plug-in for Word (Content Mapper) that uses the Word API and constrains (severely) the use of Word functions to match the DITA schema. Authors still author in Word, but are limited in how they use it. Cost is $300 for a single user; price decreases dramatically when more than 100 users, and even more so when more than 1000 users.

If you focus on the technical side of DITA/XML, you will fail with everyday Word users in an enterprise. need to:

  • take a well-defined systematic approach
  • understand and focus on information consumers
  • make the least number of changes
  • comply with content and markup standards
  • use a phased implementation approach — pilot, then go live in stages
  • need support from C-level leadership (i.e. CEO, CFO, COO, etc.)
  • apply KISS — keep it simple, smart person (i.e. ‘don’t try to  boil the ocean’)

Information consumers want:

  • accurate, actionable content
  • consistent look and feel (branding)
  • just enough and just in time content

Product knowledge triangle

The next general session I attended was after lunch. It was delivered by Hannan Saltzman and Lawrence Orin (from Zoomin software). Lawrence has only just joined Zoomin and worked for a company that implemented their solution, and presented a compelling case study on that.

My notes from this session:

70-85% of site traffic to most tech companies is looking for product content (not just docs!; includes support, forums), with only about 16% to the main website, and about 1% to sales info.

The product knowledge triangle has three parts: product documentation (writer-generated); knowledge base (KB) articles (field-generated), and forums (user-generated).

Product documentation:

  • often PDFs (e.g. admin, user, installation guides)
  • web Help
  • customers must search for this info, often filtering down by product name, version etc. to find the docs and then having to download individual PDFs to find the one with the info they need

KB/support documentation:

  • includes support, tech notes, and KB articles (usually focusing on a specific task)
  • often kept in a KB database, and accessed by case #
  • typical content includes symptom, cause, solution
  • customer needs to search the KB database separately from the product documentation

Forums (can include chat, talk back):

  • has discussion threads
  • disorganised
  • can be hard to search (especially chats)
  • typically has repeated questions, star responders, and a lot of inconsistency
  • customers have to drill down threads to find answers, even if have a search engine

Implications for enterprises regarding this triangle:

  • each place a customer goes is a separate place/dataset with a separate search function and results
  • lots of findability issues

Case study — Aternity:

  • product monitors performance of devices in a company
  • information is displayed in browser
  • monthly software releases (Agile process)
  • audience is IT/product helpdesk
  • had a help site within the site (used DITA for authoring, 2 tech writers)

Before:

  • portal with a login required to access the documentation/help
  • classic doc set (e.g. PDFs) that had to be downloaded before you could see if they contained the relevant info; if not, download and try the next one
  • had to search by product, then version, then publication
  • basically books on the web (with TOCs, indexes), and NOT search oriented
  • needed to shift paradigm to a search with the main aim of ‘findability’ (used Zoomin software)

After:

  • a single search box for everything
  • no login required
  • can quickly jump to topics
  • task topics, not a book metaphor
  • device agnostic
  • filters on side of results page to narrow down search by product etc. (all products, all versions, live filters, intelligent context-sensitive help, synonyms)

When trying to convince management of the solution, had to deal with the ‘docs are an evil necessity’ mindset so came up with a ‘Why write docs’ proposal that had a business and customer focus. Used a restaurant menu metaphor [which I think was a brilliant strategy!]:

  • make the menu (docs) public, but never the recipes (code)
  • make the menu gorgeous and tempting
  • don’t worry about the restaurant down the road (your competitors) seeing your menu posted outside — let them see how good you are, but not how you work

The aims of making the docs public are to sell, upsell, maintain loyalty, promote the thrill of what’s new, and the thrill of being the best (i.e. technical marketing!)

A typical topic page:

  • had a customer focus/relevance
  • focused on customer tasks
  • used customer jargon
  • first paragraph had the who, when, what, and WHY, followed by an example
  • included as many rich visuals as possible
  • had glossary popups (allowed topic to be pared back to basics)
  • had a place for user feedback
  • placed related KB (‘Support’) and forum (‘Community’) topic links into a side bar on the page

The result was a modern help portal that:

  • was easy — inviting, easy to find, open, easy to view
  • had a clear aim — external/potential customers (no login required), to sell and upsell the product, loyalty
  • had a customer focus — tasks, examples, rich graphics
  • was exposed — many more hits, easy to publish, search tracking, tweaked synonyms as a result of search tracking, track feedback
  • had unexpected effects/consequences — customers used the product properly (reduced level 1 support calls; nature of support shifted (questions changed — basic questions almost disappeared, and questions became more sophisticated; tracking allowed benefits to be quantified and raised the profile of the doc team — people stopped thinking of docs as a necessary evil; like support, the nature of training shifted (no more 101 courses needed); prospects/pre-sales were going to the help to find out what the product did; interest in the product increased; other business units wanted to join in.

Before, the web help pages would get 500 to 100 hits per month; after — ~25,000 hits per month. User tracking showed that customers typically spent 4 minutes viewing an article. 45% were ‘hit and run’ users (quick in and out grab of information they needed), while 55% were ‘hit and browse’.

Tracking the top search terms helped them define more synonyms (e.g. ‘db’ for ‘database’), and was used for developing documentation relevant to those search terms. Tracking search errors was also important — as a result they either created more documentation that addressed the missing info, or added synonyms to route users to the correct place. Tracking feedback wasn’t really about where the docs needed work — customers would use it to talk about the product, suggest changes to it, talk about issues they were having with it — the doc team passed these on the support people.

The impact of the ‘modern help’ was immense, in ways unforeseen when they started. The documentation is now the public side of R&D (having it behind a login defeated that purpose). The main takeaways of the project were:

  • know where your customers are looking for answers
  • ensure content is available from all touchpoints
  • prevent info overload by using filters, related articles, glossary popups
  • think content monetisation (how will making content available drive sales, reduce costs)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: