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 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