ERP 2.50:Documentation Strategy

Contents 1 Introduction 1.1 The Problem 1.2 Resources 1.3 Decisions 1.4 Requirements 1.5 Possible Options 2 Background Information and Links 2.1 Single Sourcing 2.2 XML, Docbook and DITA

Introduction

This document will record the issues and decisions that arise as we develop a documentation strategy.

The Problem

As Openbravo ERP grows in size and sophistication, it needs user documentation that looks professional, meets user requirements and that strengthens the brand. Users report that they are unhappy about:

• The scope of documentation.
• Inadequate search facilities.
• Lack of procedural information - end users find it hard to find the information they need to achieve their day-to-day goals.

We need to make a decision about how to use the collateral that we already have to meet internal and external documentation needs.

Resources

Users of Openbravo ERP can call upon the following methods of user assistance:

• The wiki.
• Online help produced using an in-house tool.

Decisions

We therefore need to decide:

• What is the future role of the wiki?
• Should it continue as the hub of user assistance?
• If we develop online help further, how do we prevent discrepancies between one source and the other?

Requirements

1. The end user should be able to access enough user assistance to complete their goals without interrupting what they are doing.

Possible Options

1. Keep the wiki as the source of truth for the product but cut and paste appropriate portions into the online help.
   • Pros: easy to achieve, can be started immediately.
   • Cons: labor intensive, product changes are hard to manage.
2. Keep the wiki as the source of truth for the product and use single-sourcing technology to create an online help output.
   • Pros: content is only written once and is therefore easy to maintain. Supports multiple outputs, for example PDF, HTML, .chm, javahelp, so could be expanded should user requirements change.
   • Cons: single-sourcing from a wiki is in its infancy. Not many people appear to be doing it and the time required to research and set up a solution could cancel out any efficiency gains. Developer resources required along with documentation resource.
3. Use the wiki as a community resource and create a help file using a standard authoring tool (for example Framemaker, Madcap Flare).
   • Pros: very easy to create a help file that looks beautiful and has full search, indexing and context-sensitivity (F1 help for example).
   • Cons: requires expenditure on tools. Would lock down documentation as a task that only the technical author could do.

Background Information and Links

Single Sourcing

Traditionally, if you wanted to produce a paper manual and an online help file for your product, you would have to write each one separately. Advances in authoring tools now enable us to write the content once, and publish it in many different ways (for example a PDF, a website and a .chm file). At the simple end of the spectrum, an author might use a package like Robohelp to create a help file, then output it as a Word document. At the other end of the spectrum, large companies use enterprise-class content management systems to store the content, manage its outputs and enable multiple authors to work on documentation products simultaneously.

XML, Docbook and DITA

DITA and Docbook are two different flavours of XML, but with strong crossovers and parallels between the two. The feeling among the authoring community is that DITA is optimized for electronic content whereas Docbook is better for print outputs. There is a discussion of the differences and similarities between the two.

Category: Documentation ERP