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 their needs.
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.
|Description||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.|
|Considerations||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).|
|Calculation||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.
|Microsoft Word||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.
|Microsoft Word||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 coaching.||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.
|Microsoft Word||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 minutes||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 in Word.|
|easyDITA||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 the map).||Total for all tasks = 30 minutes||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 team produces.
|Microsoft Word||Word has a handy function that most people don’t know about – the Quick Parts Gallery. Create 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 as needed.||10 minutes||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.|
|easyDITA||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 needed.||5 minutes||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.
|Microsoft Word||Inserting graphics into Word documents has become a pretty easy and time-tested process: 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.)||11 minutes||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.|
|easyDITA||To add a graphic: Open 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.||12 minutes||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 (non-technical)
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 elapsed time.
|Microsoft Word||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 trackable.||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.|
|easyDITA||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 your reviewers can see the whole document in a WYSIWYG display that looks similar Google Docs Word’s Print Preview.||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 changes. 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.
|Microsoft Word||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.||15 minutes||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 environment.|
|easyDITA||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.||5 minutes||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) & produce output
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 the organization.
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.
|Microsoft Word||PDF output Open the document.Select 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 Save. Note that you can also select Print and choose Adobe PDF from your available options. HTML output Open the document.Select Save As from the File tab.Navigate to the location where you will store the output.Select the type of HTML output from the dropdown.Modify the file name if needed.Click Save.Go to the file and open in your Default browser to review. You can view page source to take a look at the code, but can’t edit it.||20 minutes||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 managed. 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||easyDITA provides several routes to the publishing options, and I did it as follows: Navigate 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 Publish.When processing is complete, view the results in the Output list.Click the appropriate link to download and open the output.||5 minutes||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 production tasks.
Microsoft Word: 5 hours 31 minutes (less time elapsed for review)
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 single-source solution.
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.