Moving Toward Collaboration

Among seasoned writers, the tendency is to view DITA as a new technology that needs to be learned. Mechanically speaking, there is a lot to learn about DITA and how to write documentation using its structure, especially if the switch to topic-based authoring is accompanied by the implementation of a content management system.

My team is experiencing even more change. Our software developers have recently begun using new (to us) agile tools that are intended to speed the development process. Organized into teams, our engineers are busily meeting the goals of each sprint. If you are unfamiliar with agile development, a “sprint” is the basic unit (phase, stage) of software development and is time-limited. A sprint may be from a week to a month long. Specific goals are set for each sprint. Daily “scrums” (meetings during which everyone stands in a circle and reports their status) keep the sprint on track for completion within the time period. Things happen fast, with little time for detailed communication.

The challenge for us, as authors, is to figure out how we get the knowledge we need to write about what the sprints are accomplishing. But this is a topic for another blog post.

In addition to learning DITA and our new CMS, we are learning JIRA (a product for bug tracking) and a new WIKI for managing development content. Recently we set up our own tech writing page on the WIKI and are beginning to use it to collaborate among ourselves.

All of this is good stuff, if a bit overwhelming to learn at once. But after a vigorous start doing data analysis and lots of talk about how to write in topics instead of documents, we have fallen back into the book paradigm, each one of us taking responsibility for a single set of information that stands alone from the rest. I say “stands alone,” but it need not stand alone. There may be topics that could be shared. However, logistics demand that someone be responsible for each set of information. This is what I call “personal DITA.” As long as each person is practicing his own DITA, single-sourcing and the benefits of reused content will remain elusive. The way we work has not been DITA-ized yet!

This may seem discouraging, but I believe it is par for the course. There will be many steps forward followed by slipping back into the old ways. The key is to begin in small ways to collaborate. The next step forward is for at least two team members to work together to produce the same book. This will provide a reason for collaboration. Stay tuned.

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

The habit of why

A standard feature of a CMS is the comments field that appears when you check a topic in to the database. My initial reaction to using this field was one of rejection because I could not imagine taking the time to write about the changes I had made to the document while I was working on it. One of our consultants pointed out the desirability of being able to trace why something was deleted or added, or changed for that matter.

I am settling into the habit of checking out my bookmap without checking out all the topics contained in it. Then, I individually check out each topic when I begin to work on it. Since this method of working doesn't seem burdensome, I decided to try commenting at check-in. Soon I began to gauge my check-in times by the specific type of work completed. And, I found myself commenting even when I fixed a typo. The effort involved now seems minor, and I expect the value to be considerable, should it ever be necessary to defend the company's reputation in court! God forbid.

I'm wondering how others use the comment-at-check-in? Do you find it too much effort? Have you ever gone back to find out why an update was made?

 

 

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

Using ditamaps to provide reuse visibility

A CMS provides multiple ways to access topics, and multiple ways to reuse information, but a major barrier to successful reuse is communication among authors. Each writer must have a way to learn about topics that are available for reuse. We have decided to create a DITAmap of potential shared content based on the type of information to be reused. For example, all hardware manuals may share common topics. The same goes for driver manuals and software applications.

We created a folder in our CMS to contain ditamaps that are used for purposes other than to create deliverables. For example, this folder contains drivers.ditamap, hardware.ditamap, etc. Contained within each ditamap are complete topics that can be reused as well as topics that contain the source elements for content references (conrefs).

Each topic that contains the source of a conref is meant to also contain any derivitives that may be created based on that conref. This not only provides a logical place from which to reference reusable conref, but also visibility into how information is used to derive new information. Frequently, only a few words require changing because of the context in which a reusable chunk of information appears. Storing related conrefs in the same topic makes them easier to find and reuse.

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

First reuse opportunity leads to more questions

Another of our writers is beginning a project using DITA. Immediately, the opportunity to reuse a section from a reference topic in my user guide presented itself. Should we create a conref link to the section or split each section into its own topic? The advice from our consultant is to try things out. With experience we will figure out what works best for us. This requires a degree of collaboration that we are not accustomed to. Like remembering to update one's status in Facebook or to write a blog post, these are habits we need to develop.

Separating the reference topic into multiple smaller reference topics at first seemed the best way to go. From experience I have learned that multiple conrefs quickly complicates the whole process of producing a manual or help system. On second thought, I think it may be possible to identify one or more general DITAmaps to contain fragments of information to which a conref can be made. Even though the CMS has a powerful search capability, it still seems prudent to organize commonly-used material for easy access.

This leads me to think more deeply about the use of reference topics. They are designed for documenting software language syntax, but lend themselves to a variety of uses. The section structure begs for more than one section per reference topic. My desire to use short descriptions also implies that a single short section is not enough material for a reference topic. It may be that the best way to reuse the material in a section is to create a conref to it. 

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

Serving an author's needs

In summary, this post explores writing DITA topics that serve the purposes of the author (to improve writing efficiency and minimize the topic maintenance task) and end user (to accomplish a real-world task or solve a real-world problem). As an example, this post explains how I reverse engineered a recent manual to discover other ways to group topics in DITAmaps.

Throw-away DITAmaps

As a long-time technical writer, I naturally organize information into a book with installation, usage, troubleshooting and reference sections. The early questions I generally ask a product manager or chief engineer include: Who is your customer? What problem was your product intended to solve? How will your customer use your gizmo to achieve a business or personal goal?

Once I’ve collected the answers to these questions, I organize the book’s chapters based on user needs and perceptions and begin writing from beginning to end.

This procedure worked well until single-sourcing and DITA came along. DITA’s power is be found in the simplicity of its topic types and the flexibility of its DITAmaps. Rather than initially create a DITAmap that follows the outline of a standard book, authors can create any number of maps, some to keep and use to generate output; others to throw away when they are no longer needed. But why would an author create a DITAmap that wasn’t organized to be a book or a help system? What other possible use could a DITAmap have?

The consultant who is working with us as we move from writing standalone documents to DITA challenged me when she said that I could organize my topics to suit my needs. Later, I could create another DITAmap that would reflect the needs of the user. But, what are my needs? I have always thought of myself as a user of the material I am documenting and a strong advocate for the ultimate customer. How might my needs differ from those of the reader of my manual?

Recently, I gathered information for a manual by data-mining a recorded presentation made by the development company who wrote the code for the particular feature I was documenting. The presenter had obviously done a lot of testing to make sure the code worked. What he presented was largely a testing sequence, which did not necessarily represent how a real-life user would achieve a real-life goal with the feature. I dutifully reorganized the material using bits over here and other bits over there in the resulting manual. Reflecting on that process I ask myself, what if I had simply made a DITAmap of the material covered by the presentation, breaking the information down into topics without worrying about the ultimate deliverable? Would I have avoided redundant material? Would I have identified reusable topics? What benefit would such a DITAmap have served?

Intuitively, I conclude that, at the least, the process would have engaged me mentally with the material at a deeper level than is possible when hearing a presentation or reading a specification. The process of writing about a new subject is an educational one. Creating a DITAmap of the logical progression represented by the brain dump of an engineer may be very useful.

But, starting a writing project without keeping the ultimate deliverable in mind feels dangerous. Generating multiple DITAmaps feels like a loss of control. How will I keep track of them all? How will I know if I have covered all the user-important topics? Time could be wasted. Important information could be missed.

Reverse-engineering a document

For my latest project I started out with a DITA Bookmap that follows a standard outline for a user guide. Inevitably, as I learned about the product, the outline required revision. I added and deleted topics, changed headings and rewrote material. At this point the document is in its first review and I realize that it needs additional organizational changes.

In the throes of writing this guide I lost sight of making topics reusable. Lost in the trees, I could no longer see the forest. “I will have to go back when this is all over and edit my topics with reuse in mind,” I thought.

Before making the reuse pass I decided to take the structure apart and make a set of DITAmaps out of the topics that might have served me better as the author and perhaps saved the reorganization and rework time.

First I printed out the document and began to read it. Immediately, I found material that appears twice in the document, once at the beginning in summary form, and later in more detail. I decided that the goal of this re-imagine-ing exercise should be to discover a way to facilitate writing and topic maintenance. A governing principle should be to establish, from the beginning of the process, on source of truth for each piece of information.

I thought about reorganizing the material by source. I imagined one DITAmap for topics derived from existing help system topics; another named for the engineer who provided the information; and a third for the marketing product manager who talked me through a product use case.

This felt like it would require too much ex post facto research so I took a different approach, creating a set of DITAmaps based on product functionality. Each map contains concept, task and reference topics that are related to a function within the system. We are calling them my “maintenance” DITAmaps because, should a feature change, I could use them to update all related material without having to search the manual for related information.

Would I have come up with this organization at the beginning? Maybe. Would I have avoided writing and rewriting as I learned the topic? Maybe. I’ll try it next time.

(Another way topics might be organized could be by “big” user step. In this case, each DITAmap might include topics that cover: conceptual understanding, preparation, execution, and result with a separate DITAmap for reference material.)

Dumming down authoring?

I have a lurking fear that the end result of implementing DITA will be an authoring process that can be performed by a chimpanzee running a pre-defined system. I exaggerate. But, early on in my career I realized that one of my skills was an ability to hold the entire story about a product in my brain all at once, making connections between topics without the help of a formal written outline or plan. I enjoyed the mental exercise involved. DITA and the inevitable need to improve writing efficiency have changed my mental focus.

DITA promises to improve authoring efficiency and promote collaboration, which will speed time-to-market. As in manufacturing, asking authors to work on smaller and smaller document components could simplify the process to the point where it becomes boring. But technical writing isn't there yet. At the moment, DITA is forcing bigger picture thinking. Authors have to write for reuse. Using DITAmaps to collect related topics before writing begins might help to clarify thinking earlier in the creative process, providing a significant mental challenge that can be transformational indeed!

Here goes…

The only way to find out if this new way of writing works is to try it. Next week I begin a new project documenting a software feature. Stay tuned…

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

Define user goals

Now that we had a good idea of what had gone before, and we had the list of topics that we thought should be included in the new driver document, we decided to take the advice of all the gurus in this field and solicit input from our user community.

You might say that this should be the first step in the process, but better late than never! And any implementation of a new way of doing things into a department that has been churning out thousands of pages of helpful information for years is bound to be messy

Methodology

Lacking time to survey real live users, we decided to email a Word document with questions to the product manager and another marketing person who have customer contact.

We asked the following questions:

  • What are the user’s personal goals? The idea here is to understand what the user perceives as his or her goal, not the goal of the driver itself.
  • What are the user’s business goals? We made clear that this question is not about the company’s business goal that motivated investment in the development of the driver. What we wanted to understand is how the existence of the driver helps to meet the end user’s goal.
  • What tasks does the user need to complete to achieve their goals? Now we’re beginning to learn about the driver and what steps need to be taken to install it and configure its options.
  • When and under what conditions are tasks performed? This question is designed to determine the limitations or restrictions to achieving the ultimate user goals.
  • What are the potential distractions to accomplishing the goal? The answer to this question begins the troubleshooting section.

Results

We gathered only a minor amount of information from distributing the Word document. Our results improved when we included the two marketing people in the conference call where we discussed the results. As a result of that call, we reorganized and re-titled our topics.

It would have been better to talk to actual users, but we did learn a lot from the marketing people.

A best practice would be to understand as much about the topic to be documented as possible, then sit down with a couple of real users, or the next best interviewees, your marketing representative(s), and talk about the questions.

Currently rated 3.0 by 5 people

  • Currently 3/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

Wearing the shoe on the other foot

Learning new software has thrust me back into being a documentation user. I’m surprised at what documentation does not say.

For example, the Windchill CMS includes something called a workspace. A general overview topic in the Help Center explains that when you check out an object, it is added to one’s workspace. Then the topic explains how to clear the workspace, as if clearing the workspace is what one does with a workspace! So far I have found the workspace concept to be of little benefit.

Another concept that isn’t well explained is the idea that a topic, which is also a file, is stored in a container in the database. The name of the container is derived from the topic title when you check the topic in for the first time. I tend to revise my topics substantially before I’m finished with a document. The title of a given topic may change multiple times. It confuses and frustrates me to see the old original title appear in Windchill as the container, bucket, or shortcut name.

 

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

Content analysis

Over the summer we analyzed 40-50 hardware driver guides, with the goal of understanding how material is presented in each document and where reuse potential exists.

Methodology

First we identified a series of topics that appeared to be standard across the set. The title of each document became a row in our master spreadsheet, each topic a column in the spreadsheet.

Next, we each took a subset of driver, read them, and filled in the spreadsheet, putting an X in the column if each standard topic was present in each document. This involved some stretching and judgment calls to find the standard information, which was often buried in the text.

We added unique topics as columns to the right in the spreadsheet.

Results

Among other things, we discovered that:

·         Our documents are not really task oriented. In fact, tasks are buried in paragraphs within concept discussions.

·         Many similar topics exist across the set. Some reuse using the copy-paste-modify method exists.

·         Some topics could be reused if they were rewritten to be generic.

·         Terminology was all over the map.

Having established a general list of driver topics, we decided not to revisit past documents, but to begin with the next driver to be documented. This driver is to become the pilot project for learning about how to use Arbortext and our new CMS, Windchill.

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

The new way of working

We are learning a new tool, Arbortext Editor, as well as understanding how the content manager system, Windchill, works.

DITA promises reusable content, but it mandates a completely different way of thinking and working. Two aspects of this NEW WAY are impacting me right now:

  • Uploading topics into a CMS suddenly feels like exposing one’s writing process before anything is complete—serving what may ultimately be a delicious cake to guests when the cake is only half-baked.
  • Collaboration becomes possible and desirable, but I struggle with needing more flexibility to learn as I write and revise extensively if future knowledge requires it.

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

Implemeting DITA

This Spring one of the documentation teams to which I began implementing a Content Management System with the goal of converting all documentation to DITA-based topics. At this point the server for the CMS is running and most of the team has completed the online training in how to use the writing tools. Now the fun begins! Now we must establish editorial policies and figure out how to create reusable topics.

Our first assignment was to take an existing manual and create an outline for how to break it into topics. As a result, we realized how unique most of our topics are, providing little opportunity for reuse. I am a bit behind this process due to deadlines. The manual I am working on, however, reuses material from other books. In the daily stress of meeting deadlines it is hard to make the time to analyze content. But, the analysis step is vital to the success of the project.

 

Currently rated 1.8 by 5 people

  • Currently 1.8/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5