The proof of concept often cements the case for implementation of a new tool, but vast numbers of organizations stick with the tools they’ve always used, such as Microsoft Word, to manage vast repositories and complex processes. TechWhirl and easyDITA worked together to conduct a proof of concept comparison between Word and easyDITA that used real-world scenarios for documentation tasks. We found that:
- Most organizations fail to fully utilize the functionality available within Word.
- Nonetheless, accomplishing many of the tasks of organizing content into reusable “units” is far easier in easyDITA, which can save the typical organization enormous amounts of time and resources down the line.
- easyDITA does require training or coaching support, specifically around the tasks of creating document maps and organizing content elements. Upfront investment in training and understanding structured authoring pays off over the long-term.
- Separating the organization/structuring of content from the process of creating it is much harder to do than most organizations realize, but a system such as easyDITA allows them to create the processes that match their needs.
I’ve read the business cases and the product literature. I’ve attended seminars, webinars and conferences. I know that implementing DITA to manage technical content can be a great idea. And still, I continue creating documentation in Word (and sometimes I suffer with PowerPoint, and when I’m really lucky, some sort of HTML-based content management system). Why? Practical considerations—because that’s the tool the company lets me use.
Sound familiar? If not, it should, because hundreds of
companies, large and small, never even consider investment in a content
management system beyond SharePoint and “whatever the IT guy recommends.” It’s
a challenge for technical and marketing authors to win this argument and slay
the Microsoft Word dragon to gain tools that actually do structured authoring
and reusable content. But, it can be done.
How? Content teams need to take a step back and ask
themselves “How can I prove that it’s worth the investment?” The answer is that
they should do a proof of concept that looks at the reality of their situation.
Real tasks, real authors and reviewers, real data, real roadblocks. And do this
proof of concept comparing Word with a vendor that offers a solution that fits
I know. This is hard and thanks to smaller staffs with
increased responsibilities it may be filed in the someday / maybe folder or even
the folder of a circular variety.
Since we have the time, energy and interest, TechWhirl together with our partner easyDITA decided to do our own pilot test. We set up some real-world scenarios, which are familiar to most authors of technical content. Our test spans the entire process: authoring through to final production of output. We documented how the effort, the process, and the final output actually compare between Microsoft Word and easyDITA.
Given that I’ve been a Microsoft Word expert user since
before the turn of the century, it made sense for me to tackle this effort. I
know stylesheets, change tracking, document merges, graphics formatting, and
more than a few obscure tricks to shorten the time it takes to do stuff in Word.
I’ve also used quite a few content management/authoring systems and can pick up
new tools fairly quickly.
For the evaluation, the small group of us that is TechWhirl worked
with easyDITA to define goals, the tasks, the metrics, and the sources of
content. To ensure a fairer comparison, I then scheduled a fairly detailed demo
of easyDITA, where I had the opportunity to ask questions and try
functionality. Prior to the demo, I had no hands-on experience with easyDITA.
Measure the time it takes to author,
review, and revise, format and publish assignments.
|Goal||Compare the time-to-market for new and for revised content, broken out by phase: Author, Review and revise; Format and publish.|
Produce content as PDF and as HTML. Include
only the time it takes to accomplish each task (e.g. do not include
wait/response time for reviews and approvals).
Document and compare, in hours and minutes,
the time it takes for each step in the three phases.
The Test: Content Development Microsoft Word vs easyDITA
I compared completion of these tasks by first walking through all the steps in Microsoft Word (I use Office Professional 2016, 64 bit installed on a laptop running Windows 10). I then went through the steps using easyDITA 19.0 in a cloud environment set up by Jorsek and accessed via Google Chrome.
At the highest level I took the following steps:
- Set up style sheets.
- Produced document outline / product map.
- Entered content in the system.
- Created/added “boilerplate” content.
- Added graphics.
- Reviewed and marked up content.
- Revised content.
- Set up output parameters and produced the final output.
Step 1: Set up style sheets
Style sheets control the look and feel of the content output and eliminate messy and time-consuming efforts to manually format text during content creation and revision. Style sheets allow you to concentrate on creating effective, accurate content rather than the “make it look pretty” tasks that can consume a content developer’s day, or month, or entire professional life. They also aid in organizing content in a hierarchy that makes sense for the content consumer.
In Word I began with a blank document and modified 13 of the standard
styles to suit my personal working preference. I could have stuck with the
default styles that word provides, but I find that working with my own
“default styles” keeps me from being distracted.
Later I added a style to address the need for a legal disclaimer as a
warning rather than a note.
|35 minutes||I never cease to be amazed at the number of professional writers/communicators, who have no idea what Word styles are, much less how to use them to streamline their document creation. Thus, this time requirement may be significantly higher in many organizations where writers can get bogged down in applying formatting manually .|
|easyDITA||While we discussed at high level how styles are managed in easyDITA, we determined that setting up new styles would not be a productive use of time during the test, since in real world scenarios would be set up prior to writers starting their work. So I used the default styles included in the outputs within the easyDITA environment.||5 minutes||
I just had to select the output that used the styling I wanted. I
tried the different output options that were set up. One didn’t work at all,
but the other two quickly produced a final PDF file.
Step 2: Produce document outline / product map
The document outline (or product map in the structured
authoring world) serves as the single most important step in developing
content, no matter what tool you use to do the actual development. The outline
tells the author what should be covered, and in what order the content needs to
be presented. Its natural hierarchy allows you to maintain consistency when
building content of specific types, and reviewing the outline allows you and
your SMEs to identify gaps and irrelevant content at the start.
I reviewed the style settings and then built the outline applying the
style settings where appropriate.
|120 minutes||Creating an outline (the closest equivalent to a “product map” in Word) is easier if you know the built-in style settings and have done outlining for more formal documents.|
|easyDITA||A product map is essential for effectively managing structured content, and once you understand the elements, is relatively simple to maintain. A little additional coaching from the easyDITA folks set me on the right path, and it certainly becomes easier as you work with it more often.||
240 minutes – before coaching
110 minutes after
I found creating the document map in easyDITA pretty challenging, and
had quite a number of false starts, mostly due to my unfamiliarity with the
elements and the naming conventions used in the test case.
Step 3: Enter the content in the system
What technical writers like and do best… creating content
that addresses audiences’ needs and engages them.
Typical word processing/content creation steps in Microsoft Word
include, creating a new document, locating the document in a relevant
repository, entering text, inserting graphics, applying styles, etc., as
needed to convey information in an organized and clear manner. Styles allow
creation and automatic updates to the table of contents (TOC).
Authors also review new content as they work, and switch between
entering text in a document and viewing the application or using the product
to ensure they capture information correctly.
Total for all tasks= 60
The test included adding new content to an existing document, so the
additional time it took to add the content in Microsoft Word came primarily
from locating the appropriate places in the document.
The TOC feature, which I also used and updated as I worked, is
essential to maintaining long documents, and requires a knowledge of styles
Organization of topics takes place in the product map, so creating
new content includes both creating a new topic with the appropriate ID and
topic type, and adding new content to an existing topic (after locating it in
Total for all tasks = 30
In easyDITA, creating topics is pretty simple. And because
they’re separate elements, you just have to insert them as topics in the
correct location on the map. I found it a bit confusing at first to add steps
or sub-steps, but once I had the right combination, it was a snap.
Step 4: Creating/adding “boilerplate” content
Anyone who has created technical content, such as user
guides or job aids, for more a couple of days, understands the need for
boilerplate content. Identification of intellectual property, disclosures and
disclaimers, generic notes about a process or function, and specific warnings
all constitute content which gets reused within and among the documents the
Word has a handy function that most people don’t know about – the
Quick Parts Gallery.
a piece of content to be reused inside the document.Apply
a style (or create a new style for it) using the Home tab.Highlight
the newly created text.On
the Insert tab, Click the Quick Parts option.Save
it as a Quick PartChoose
Save selection to Quick Part Gallery.Insert
Quick Parts is a VERY rudimentary method for reusing
content, but it certainly beats locating a document with all your boilerplate
and copying and pasting the correct item to the correct location.
Create a topic to be used as boilerplate, apply an ID and reference
type, save it to the correct location in your repository, and insert as
Boilerplate is just a different topic in easyDITA. Once you
create it, you can insert as needed, and it’s VERY easy with the Docked
display that shows the map and the elements within their folder(s) in the
hierarchy you set up.
Step 5: Adding graphics
Graphics serve a lot of purposes in technical content,
providing visual cues, illustrating concepts, identifying parts or locations
where a task should be performed. Managing graphics in a central location, and
using a good naming convention to identify them for ongoing maintenance is a
best practice no matter which authoring tool you use.
graphics into Word documents has become a pretty easy and time-tested
Put the cursor where the graphic needs to be.Choose Pictures from the Insert tab.Navigate to the folder and select the graphic source
file.Click Insert.Apply formatting options using the Picture tab (e.g.
as resizing, cropping and text wrapping.)
If you insert a graphic by reference in Word, you will need to ensure
that the path is correctly identified (if it’s on a local drive, you’ll never
see it in the finished output). Otherwise the factors contributing to time
required in Word are locating the source files, and any resizing or external
formatting you want to do.
To add a graphic:
the topic where the graphic should be locatedClick
the + symbol to the left of the content.Select
Image from the dropdown (you may also want to choose Figure, which adds text
for a caption.).Navigate
to the location of the graphic in the content library.Highlight
and click Select.
I found inserting graphics to be about the same level of
effort in easyDITA, with a tiny bit of extra time required to locate the
images in the correct directory
Step 6: Reviews and content markup: Technical & SME Content Reviews
Reviewing content remains challenging for most organizations
for several reasons, including the tendency for reviewers to procrastinate, and
then to provide formatting and proofreading changes while failing to review for
accuracy and relevance.
The actual time elapsed for the review/mark up phase of any
document, regardless of system, depends a lot on the responsiveness and competence
of your reviewers. The authoring tool doesn’t have the capability to determine
processes such as who has final authority to determine grammar, syntax and
stylistic changes, and such battles can also contribute heavily to the total
In a typical Word environment, the file needs to be named properly,
sent as an attachment to an email (or stored in a central location), marked
up, saved as a new version, and sent back to the content developer. The
content developer then must accept or ignore changes, make additional
revisions and save a new version of the document to ensure that revisions are
1 hour on content
35 hours elapsed
In Word, this can be made infinitely more complex and troublesome if
documents are not managed in a central repository. Review by attachment is
cumbersome and time-consuming, and in my experience, reviewers are less
likely to understand the markup (track changes) and commenting functionality
in Word, and tend toward horribly inefficient processes like manually
formatting new content in red or purple. If you have a decent SharePoint
workflow set up you can save a lot of time, but reviews need to know how it
works, whether they have access to the location, among other concerns.
For the lay person, easyDITA reviewing operates more like Google
Docs. Once you have the link to the location of the document, you can suggest
edits and provide comments, which the author can then resolve fairly quickly.
Create a document map and add the appropriate topics and references, and
30 minutes content
26 hours elapsed
This is probably the biggest area of time savings for your
organization over the long run. In an easyDITA environment the process of reviewing
content happens in one centralized location. No passing around drafts via
email attachments, easy viewing of revision history to see who made what
The reviewing and suggesting modes allow the content team to assign
levels of editing to technical or non-technical reviewers without messing
with version controls or undoing edits.
Step 7: Revise content
After a number of review rounds, the content comes back to
the author for revisions. While this includes accepting or rejecting changes,
often the author must also review the changed content to ensure it remains
cohesive and understandable.
I used track changes functionality to locate each modification or
comment. Then I decided whether to accept or reject it, and whether to do
additional revisions for clarity. Once I addressed the review comments, I
deleted it from the document and saved a new version.
Hunting in a 245-page document to locate content to be
revised can be challenging if the reviewers have not used track changes. Even
if they have, authors have to be conscious of the best way to version the
drafts to ensure the actual revisions aren’t lost in a multi-author
I opened the topic in Reviewing mode, took a look at the suggested
changes, and using the Reviewer vertical tab to the right of the content
pane, chose either the check or x button to accept or reject changes, or the
Resolve button to note that action was taken to address the comment. To make
additional revisions, I just changed back to Editing mode.
Another function that is very easy to understand and
master. Changing modes saves lots of time otherwise spent in saving new
versions and turning track changes on and off.
Step 8: Finalize output parameters (file types and formatting) &
After the team (or lone writer) makes the final content
revisions, and receives approval, it’s time to produce the final output…
typically PDF files (to be printed, emailed, or linked on a website), html
content (for in-app help, or website content, or knowledge bases). And
sometimes you need to create multiple outputs. For our test, we kept it fairly
simple and only created PDF output and HTML.
One of the biggest differences between Word and eastDITA
became apparent at this step. I’ve found that organizations still relying on
Word often have templates based on brand requirements, sometimes including
standard styles, but often not. Authors in this scenario may set up their own
styles to save time during output, but I’ve found it’s rarely consistent across
easyDITA eliminates the potential for such inconsistencies
because, as a DITA system, it automatically applies formatting on output.
easyDITA uses a PDF generator with standard and customizable templates so
organizations can set-up their publishing scenarios once and writers don’t have
to adjust anything.
Save As Adobe PDF from the File tab.Give
the file an appropriate name.Navigate
to the location where you will store your output.Click
Note that you can also select Print and choose Adobe PDF from your
The actual time on setting up output parameters can vary tremendously
based on what kind of output you have to produce, and whether your styles are
PDF output in Word for this project was fairly simple, since we
weren’t looking at odd page sizes or form generation, and didn’t need to set
up for backwards compatibility. Mostly the time comes from configuring and
checking various page settings such as bookmarks and hyperlinks.
HTML output has always been challenging in Word, since it introduces
so many proprietary and bloating spans and divs. You cannot view the actual
html code within Word; other tools are required to clean up HTML output. You
can never go directly from Word to Web.
easyDITA provides several routes to the publishing options, and I did
it as follows:
to the location of the ditamap file (the type displays as Book-Map)Click
the Publish button in the upper left corner.Select
the publishing scenario from the left column.Enter
a description of the output.Select
the output type(s) from the transtype field.Click
processing is complete, view the results in the Output list.Click
the appropriate link to download and open the output.
In easyDITA output selection is very easy, and the test
case scenario offered several preset outputs for PDF, HTML, xHTMl, and
HTMLhelp. It’s likely it would take more time to set up some configurations
that comply with various brand standards for the organization, but once set
up, selection and publishing go easily. And you can produce all your output
types at the same time, which is very handy!
Our test involved a total of three people—one experienced in
Word (me), one experienced in easyDITA and one who served as a reviewer, so
your results on some of the tasks could vary significantly from ours. Overall
these tasks were pretty representative of typical content authoring and
Microsoft Word: 5 hours 31 minutes (less time elapsed
easyDITA: 3 hours 22 minutes (less time elapsed for
review & after coaching)
You may be thinking that this wasn’t a true head-to-head
test, and in several senses you would be correct. TechWhirl is a tiny
organization, with relatively small amounts of content to manage. But we all
have experience working in medium and large organizations with byzantine review
and repository management processes. Thus, it became pretty easy to extrapolate
this experience to a much larger organizational scenario.
Once you understand the context around single-sourcing and
begin thinking through the production process, easyDITA is a clear winner for
overall time spent on a typical documentation project. The functionality
required in the content creation/modification process is pretty simple and
quite intuitive and would be the easiest part of a transition to a
However, understanding the single-sourcing structure
required and how to put content components together is a pretty significant
initial time investment. Even understanding as much as I do about organizing
and designing content, getting through the first couple of weeks of “playing
around” with easyDITA took a lot of rethinking of my entrenched habits. True
information architects who have deep understanding of content elements and
categorizations can probably easily do the mental mapping required to create
effective document maps. The average content writer probably would be confused
and frustrated by it, but will easily adjust to the requirements of producing
specific content types and managing them centrally.
This probably comes as no surprise to the content
strategists and DITA consultants out there. The actual exercise of setting and
publishing some documentation tasks requires much more thought and planning
than many organizations with entrenched process have ever considered. But at
the end of the test, I have a much better grasp of the importance of
categorizing the type of content required and organizing it in a structure that
optimizes reuse and streamlines maintenance. The coaching provided by the
easyDITA folks is the kind of specific training they provide to new customers
as a matter of course, and it certainly made the difference in understanding
how to create the document map and use it effectively.
Using the Comparison to Bolster Your Business Case
Saving one-third of the time required to manage typical
documentation projects is an easy win for the business case. The overall
improvements in reuse, reductions in duplicative and error-prone content aren’t
as easy to pinpoint using this particular test since it covered such a limited
timeframe. The savings for an organization will be significant when the return
is measured over quarters and years. When you consider how much content your
organization must manage in the face of constantly evolving customer
experience, complex regulatory and compliance requirements, and organizational
models that change frequently, investing in structured authoring solution such
as easyDITA becomes an excellent business decision.
- What Is DITA? (Jacquie Samuels, on TechWhirl)
- What Is DITA? (downloadable Getting Started Guide from easyDITA)
- easyDITA Explainer videos (videos designed for new DITA users)