just write click

In trying to modify multiple Author-it topics (okay, 5,119 topics) with variable assignments, I have had to work with the XML output that Author-it exports.

To export to XML, you select a topic or multi-select topics, then right-click on the selection and choose XML > Save to file.

Turns out, Author-it outputs its XML encoded with UTF-16, but apparently most Windows applications understand UTF-8. When I tried to open my freshly export XML file, XML Copy Editor gave me an error.

So I had to discover how to convert the XML from UTF-16 encoding to UTF-8 (and you can’t just open it in Notepad on Windows and change the 16 to 8, there are other embedded characters indicating the encoding, and, well, it’s encoded.)

First, I used the identity transform documented many places, my favorite place being the XSLT Cookbook, to convert the Author-it output to UTF-8. Here’s the XSLT code for that:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:output encoding="utf-8"/> <xsl:template match="@*|node()">

	<xsl:copy>	 	<xsl:apply-templates select="@*|node()"/>

	</xsl:copy> </xsl:template>

</xsl:stylesheet>

I just ran the above transform against the AuthorIT Objects.xml file I exported, using the Instant Saxon XSLT processor.

Then, I wanted to remove all <VariableAssigments> elements, effectively removing an entire node. Again, the identity transform (or copy transform) was effective. And, I learned that I had to identify the AuthorIT namespace thanks to this excellent helper article, Handling Default Namespaces on topxml.com.

<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"

xmlns:ait ="http://www.authorit.com/xml/authorit">

<!--Match everything using identity copy-->

<xsl:template match="@*|node()">

	<xsl:copy>

	<xsl:apply-templates select="@*|node()"/>

	</xsl:copy>

</xsl:template>

<!--Remove all the VariableAssignment nodes-->

<xsl:template match="ait:VariableAssignment">

	<xsl:comment>Removed VariableAssignment element</xsl:comment>

</xsl:template>

</xsl:stylesheet>

This transform is pretty dangerous, though, because it’s taking away all the VariableAssignment elements, and you might have valuable metadata stored that you would quickly blow away. So use with care.

This workaround is likely also useful for DITA and XHTML files, because Author-it outputs its DITA and XHTML files as UTF-16. I haven’t investigated its usefulness for those areas, but a quick search on the Author-it-users group on Yahoo revealed that sometimes people want UTF-8 rather than UTF-16. So, I hope this helps.

Our team is so excited for the new Author-it version 5.0 that we invited other Austin techpubs teams over to our office to watch the US & Canada webinar. It was like a movie premiere. Okay, we’re not really that big of dorks. But we had a good time with it.

By my calculations, it was about four AM Australia time but both the presenters were troopers, even when the typed-in license key didn’t “take” during the migration portion of the demo. All of us in the room empathized with her and she smoothly avoided any delays.

I’m mostly excited about the new interface. And Australians New Zealanders say “ribbon bar” so sweetly. It’s such a nice update. I’m really looking forward to using it. The organization of styles and templates makes sense as well, and I am glad to have separation between paragraph styles and character styles.

The search bulk-ups contain the features my co-worker was looking for - search within a folder and match case or whole word. Also the search within a topic as a customizable panel pop-out is going to be highly useful. That new editor interface is especially exciting. It reminds me of XMetal’s editing environment.

We can’t wait to start trying publishing profiles. We wanted to just start clicking in the dialog boxes displayed during the demo. Their knowledge base says that eleven profiles are shipped right out of the box (mapped directly to publishing outputs). The output types I see in version 4.5 are DITA, Word, PDF, HTML, XHTML, HTML Help, Microsoft Windows Help (RTF-based), Java Help, Oracle Help, XML, and Author-it Website Manager format. Since that list adds up to eleven types, I guess there are no new outputs with this release.

While we don’t currently have a use for Author-it Xtend, I found it fascinating as a concept. Why would a techpubs department pay money to a vendor for an embedded search engine to try to encourage writers to re-use? Why not just spend that money in training (or hiring) writers to think more about topic orientation and re-usability?

My co-worker pointed out that in a translation situation, Xtend might pay for itself in one translation round. It seems so very Google-like. There’s this sliding bar for more Fuzzy matches and more Relevant matches. There’s color coding for matches. I’m automatically drawn to it like a moth to a back porch light, yet I’m not sure of the best applications for the search hits nor what problem teams should expect to solve with this functionality. Perhaps someone can tell me the best scenarios for this add-on?

We copied the Questions and Answers from the webinar, and people asked plenty of questions. Here’s just a sampling - does 5.0 run on SQL Server 2005 (yes), does it run on Windows Vista (yes), questions about the new Project Manager (purchased as a separate module but is integrated into 5.0), is the 5.0 upgrade covered by a maintenance contract (yes), can you upgrade from 4.3 to 5.0? (yes), are presentations part of 5.0 (yes), and the final question was a good comparison: Can I use the Filters (Variables) on the Publishing Profiles as I would have used conditional build tags in RoboHelp to include/exclude content from specific output types? Am I understanding this correctly? The answer: yes, that’s correct.

So, exciting new features abound and we can’t wait to get our hands on them. I’ll keep you posted on our progress.

Adobe has announced a Technical Communication Suite, combining FrameMaker, RoboHelp, Captivate, Acrobat 3D, and Flash, available in October 2007 for $1599 or $999 upgrade pricing if you already own one of the tools. This price point is well below what buying those products individually would cost (compare to $3600). I’m about a day late to the flurry of blog posts, as there are many bloggers commenting on this release, but many of them are focusing on the FrameMaker to RoboHelp single sourcing aspect, including the Adobe Technical Communication blog.

Scott Abel, The Content Wrangler, noted the price temptations, especially for people currently on RoboHelp. I’d just add that the upgrade price is the same price as Adobe Creative Suite 3 Web Standard ($999).
Dan Ortega’s message from Astoria appears to be but there’s no enterprise workflow and it’s a desktop solution, meaning, tech writers will still be the only users in a company using FrameMaker. Charles Jeter notes the same lack of collaboration in the suite in a nice wrap up post as well.

Sarah O’Keefe notes that most of her clients are going lighterweight than FrameMaker for their XML solutions.

Bill Swallow (techcommdood) notices that you can only go from Frame to RoboHelp, not back.

While single sourcing is always interesting to me, what I’m curious about are the use cases for Captivate, Acrobat 3D, and Flash, when using this Suite. I’ve used FrameMaker and RoboHelp in the past, but haven’t gone beyond the trial version of Captivate. So I looked at the webinar listing and there are hints at use cases that are an interesting sweet spot for the technical writer who wants to move past the static manual into interactive user assistance - not to mention the technical trainers looking for the correct tool to build interactive demos. Here are some catch phrases I lifted that might be just marketing-speak, but also might speak to where our profession is headed.

• track help system usage
• leverage existing content to create interactive help or performance support
• question randomization
• animation imports from PowerPoint
• do this cool buzzword stuff… without the help of your engineering department

So perhaps a key aspect of what Adobe has heard from tech writers all over is, we want to do cool stuff, but we’re not getting the resources we need to program the cool stuff.

And indeed, the webinar folks seem to want to help define where we’re headed and how we’ll get there. To quote from the intro paragraph, “What does this mean for technical communicators, instructional designers and eLearning professional today and tomorrow?” As go the toolset, so goes the career? I suppose that the skill demand certainly shapes what you learn as a technical communicator in order to stay employable. Does your software toolset make you do your job a certain way?

I thought I’d continue posting about my experience with Author IT since my initial review of AuthorIT. This past month I’ve been exploring ways to help out with the Author IT nuts and bolts, doing maintenance-type and infrastructure tasks such as changing the on-screen style formatting and revising a book template.

I’ve also been learning more about what is involved with the overall tasks of maintaining single source with nearly 20,000 objects in your library. Objects can be topics or books or hyperlinks or index entries or graphics or… many other items, so I’ll have to dig deeper to get a sense of how many topic objects we deal with daily. Ah, here we go - do an Advanced unqualified search filtered for results Of type “Topic Object” and then select the ones not marked “Obsolete” or “Orphaned” (meaning not used in a book object) and the answer is, we have over 7,000 topic objects in our library.

I maintain that the learning curve is steep but I’m fortunate (or sometimes unfortunate) that I’m approaching these tasks with an idea of how I think it might work. Plus I have an Author IT expert sitting in the office next to me who still answers my IMs when I ask Author IT questions. (Thanks, Mary!)

Changing the state

It is still taking me a while to get accustomed to the workflow that requires that I change the state of an object before making edits to it. If the topic I want to edit isn’t in a writeable state, then I can’t make my edits until I locate the object so I can right-click it to change the state. Maybe I’m missing some shortcut to how to change the state while editing a topic’s text. I’ll have to poke around the tabs a while. It’s more likely that I need to make a shift in my workflow and remember to select the topic objects I want to edit, change the state, and then begin the edits.

Search mechanisms

My understanding is that there are two basic search mechanisms and both are rather underpowered for the amount of legacy information we have stored. (I’ll have to get a topic count to give real numbers here.) The first search mechanism is searching the entire collection of topics and books and sub books. The Advanced Search checkbox is always checked in my environment.

The second search mechanism is on the actual text within topics - you can search for text within a topic, within a book, or within the entire library. This mechanism is found from the Edit > Find menu command in AuthorIT Enterprise Edition.

What I’ve found recently, however, is that you cannot replace formatting on the found items. This limitation means that you could have semantically tagged items that are not able to be retagged. For example, if you had tagged all your menu items as “menucascade” but needed to change the tagging to “breadcrumbnav” you would have to export the topics to an XML editor and do search and replace there. I don’t yet know how to batch export say thousands of topics to do this search and replace to get the semantic tagging you wanted. This analysis and potential workaround is based on searching within the Author-it Yahoo Group’s messages, so perhaps there is another way to search for text and formatting and change both the text and the formatting but I haven’t found it yet.

Even with these two search mechanisms at our disposal, we find it easier to use a Google search tool on our external database at docs.imis.com, then right-click on the HTML page to get the topic ID, then use that topic ID to search the AIT object database.

Author IT Yahoo Group

Now, I just went through the Yahoo Group messages again to learn more about the searches in AIT, and I really do like the community there. People are very helpful and still maintain a nice sense of humor and goodwill. That’s an important aspect of any tool selection I think. Anyway, there is a way to search within a set of found items, and that is to do a Search using the Search tab first, then press Ctrl+A to select all topics found that match the search criteria, and then do the Find and Replace command on the selected topics. That search also revealed a potential limitation of AIT’s inability to find period space space and replace it with period space (explanation of why period space is correct, because The PC Is Not A Typewriter).

A third search mechanism that we could make use of but that doesn’t yet exist would be the ability to search within a folder. We can use the trick mentioned above where you select all the objects in a folder then do a Find. A Folder in AIT is just a representation of the objects in a collection within a folder in the CMS of AIT (sorry, too many acronyms to qualify as a real explanation, but it’s basically another view of the database but not searchable within each Folder). But that’s a find on text, not a find on objects or metadata on those objects.

Variables to substitute text values

I find that the variable mechanism is a little bit clumsy. Variables are simply text enclosed in angle brackets <substitutethisforthat>. So you still have to do a search and replace for text when you want to choose a different variable name. If you use angle brackets in your documentation, AIT has to be told specially that you meant to do that and that those should not be resolved to a variable name. So, if you really want angle brackets to appear as angle brackets and not resolve to a variable, you have to use the HTML trick of ampersand lt semicolon.

Running AIT publishing from the command line

One nice feature is the publishing engine’s batch processing that will even output the commands for you so that you can include it in a batch process. We found that the outputs are always placed within the users folder that is logged in to AIT, despite using a documented command line parameter where you feed in a user and password for running the batch processing. Mary found a nice workaround where she just copies the files she needs out of another folder (the _Output folder in our environment), but it seems like a waste of disk space to me to have a second copy of output in each user’s folder. We can do some cleanup using the batch files to ensure that disk space is freed up, however.

Magical price point

Let’s face it, since it’s in the four figures for a seat license, Author IT is a relatively inexpensive all-in-one single sourcing tool that has both a straightforward editor and a content management system. A small techpubs department looks pretty darn good when they can deliver manuals and help as part of an automated build in a lights-off no-touch system. And the savings in translation costs when you single source are unmatched.

Where AIT “feels” inexpensive though, is in the slightly outdated interface (why can’t it remember the window size after being shut down?), somewhat underpowered search methods, and so far, I just can’t shake the general feeling that you’re not really owning or editing “source” files but rather some Word-like representation of the source.

Still, it works wonders and lets our small techpubs department output some high-quality professional content, more content than possible without a single-sourcing tool. So I’ll face the learning curve and continue to climb it.

I’ve been keeping an eye on the search keyword list for this blog. The hits are typically from search phrases like “technical writing” “masters degree” and “agile documentation.”

But one phrase that I found interesting was “just write what I say.” I would guess that the person is seeking voice recognition or speech recognition software, specifically verbal transcription tools. I suppose Dragon NaturallySpeaking is the first product that comes to mind, but there are OS-based options as well. I like their product’s tagline, “Turn talk… into text!” so props to them and a link.

Speech recognition can be integrated into certain programs on Windows XP SP1, such as Microsoft Word and Notepad, as this article from September 2003 describes, but you need Microsoft Speech Recognition Engine v5.0 and naturally, a microphone and hardware that can take in the speech sounds.

Mac OS X has speech recognition integrated as well, and you can even play chess with the computer giving it voice commands, according to this web page.

So, I’m writing this post to gather some traffic but offer useful information while collecting those hits. Give back, I say. Let me know if you found this information useful.

I received an excellent question from a reader about his eagerness to use wikis for his product’s doc set, but he came across conflicts and issues when he questioned the practicality of maintaining a wiki for his large set of documentation. Here’s Paul’s well-phrased request for information.

I am considering using a wiki for documentation projects, but have been coming across some showstopper issues. Here is the story:

Our documentation set is large. We only want to maintain one set of files. Therefore, any changes in the wiki would need to be automatically synched with the source files.

The obvious suggestion is “just make the wiki your source files.” However, it is not as simple as that, for a few reasons.

• First of all, we need to generate attractive offline documentation in online help format, viewable across several operating systems. No wiki enables an elegant way of doing that.
• Secondly, we have a bunch of conditional text–our existing documentation comes in six different versions. I have not found a good way to integrate the different conditional tags into a wiki, while maintaining it in both our sources and the offline output files.
• Finally, wikis almost by nature do not support DITA. Wikis are designed to be simple and easy to understand. However, that approach negates many of the advantages of structured writing.

For these reasons, I currently see wikis primarily as a collaboration tool. But they do not have the features necessary for complex technical documentation.

Do you have ideas for how we could get around these issues?

Oddly enough, on this particular day, another reader wrote in about similar issues with wikis, but they have started to overcome them. He listed the issues succinctly, saying:

I’d say that there is quite an art to creating wiki doc from a couple of perspectives:

* conversion
* building out the infrastructure
* look-and-feel issues
* style issues
* review issues
* basic editing issues

Even with all these issues — — however, the immediateness of the experience, the ease associated with making changes and the creation of links and containers, and the modern look and feel really make wikis a fascinating competitor with other, much different technologies. How many other industries move off in such opposite directions (wikis vs. dita)? It’s sort of like trying to figure out whether cars should run on gas or steam!

The CEO of Confluence came through a few weeks ago. He was pointing out to the following as an example of a company that had developed wiki doc:

http://www.gigaspaces.com/wiki/dashboard.action

Here are two more you might find interesting if you don’t already know about them:

http://docs.codehaus.org/display/GROOVY/Documentation

http://www.aptana.com/docs/index.php/Main_Page

And here’s the part that is amazing to me - in a follow up email, Paul answered some of his own questions and said that the gigaspaces.com wiki is one wiki he is investigating further. For example, by talking to one of the writers, he learned that their wiki has 1300 pages, and reuses many pages through the [include] command or transclusion, which is the inclusion of part of a document into another document by reference. My original response to Paul talked about DITA as source files and wiki as an output from those source files. I learned that Robohelp does something like that, with source files and wiki as output, and this blog post mentions round-tripping the content back to Robohelp.

Naturally, I have some ideas about DITA and wikis. My post about DITA Storm built into a custom wiki describes a hybrid approach, with DITA files as the source and editable pages. Paul takes that idea one step further, saying that you could have the internal technical writers see a DITA editor interface to the wiki, but have end-users write doc in a simplified editor with fewer tags. I like that idea.

There’s also the possibility of a transform from DITA to wikitext. A search on the dita-ot-developer list on sourceforge.net revealed that Deborah Pickett was writing such a thing for her employer last April. I emailed her and she generously gave me her XSLT source files, but said that she gave it up when she found that “The whitespace rules for wikimedia meant that anything fancy would end up being better written in wikimedia’s pretend HTML format anyway.” Hm. I haven’t tried the transform yet myself. Bob Doyle has done a lot of DITA to WikiMedia transformation to pre-seed the ditawiki.org with content, and he says “The Perl script for conversion to MediaWiki is publicly available at http://www.jtidy.de/conv. It has a major flaw in that it does not convert URLs to hyperlinks.” Again, I’d need to try it myself to see whether that approach would work and if the technology scripting is worth the effort.

Now, for everyone pondering wikis and DITA, an absolute must read is this great article by Paul Prescod, The Convergence of Structure and Chaos. Not that it offers practical solutions (although he hints at some at the very end), but it maps DITA concepts to wiki concepts.

I’ve also been noticing that people are trying to automate getting content from their support forums into wikis… Check out this poor intern’s daunting task: http://ask.metafilter.com/62679/Automated-Media-Wiki-Page-Creation.

I guess to answer my own question about where wikis fit in tech doc, I currently see wikis as supplemental, not source doc from which to make other things. I probably lean towards seeing a wiki is another output from perhaps DITA source. Sure, there would have to be a loopback mechanism to get the contributed parts of a wiki back to the source files, and I’m not sure how automated that could be. But, I would love it if vendors could convince me otherwise, and frankly, I keep hearing about Confluence and their examples are compelling.

So I share with you these side conversations I’m having in hopes that the information here helps others in their quest to offer wikis to their end-users. Users, write the manuals. But make sure us writers get to meet our objectives as well.

As a final departing thought, I share the machine is us/ing us video, containing the best description of Web 2.0 and new media I’ve seen to date, created by a cultural anthropologist. It’s about five minutes long, and a thought provoking piece.

One of the questions in it that stuck in my mind was the question at about 3:00 minutes, “Who will organize all this data?” And the typed and re-typed answers after a screencast or demo of del.icio.us:

We will.

You will.

I’m now writing in an AuthorIT environment. My first learning task is to find out the proper pronunciation, is it Author Eye Tee? Or Author It? Let’s see what wikipedia has to say about AuthorIT. In their article, they consistently refer to the product as Author-it, so I would suppose the second pronunciation I proposed is the correct one. Plus, the AuthorIT website has Authorit throughout. Internally we call it AIT for short.

At first glance, the product looks and feels like a database-centric content management system because of the initial connect you make is to a SQL Server database. But in fact the way you browse the system is folder-based, as if I were using Windows Explorer. So far, so good, except that I’m not yet completely familiar with the way that the CMS folder structure is set up based on our Function-based teams. However, we have a Helpsite that lets me browse the current content in another way and has a decent search mechanism and index to allow me to look for the topics I’d need to update.

What I’m doing now to get started as a greenhorn with both the toolset and the product I’m documenting is to peruse the Helpsite which is organized by tasks and features of the product, and then determining what topics need updating for the particular feature I’m working on, and then right-clicking and getting Properties on the page I want to update. Next, armed with the five-digit number that the HTML file is named, I do a search in the AuthorIT database to find that exact topic, and then make my edits. Whew.

One incorrect assumption I had going in to the AuthorIT environment was that editing is all based in Microsoft Word. Not true at all, my AIT trainer protests, the editor is AIT’s own, but AIT does a good job of outputting to Word formats and you can use VB macros to format the output as you wish. I’m still learning so I’ll let you know what other incorrect assumptions I’m finding otherwise about.

The other thing that strikes me right away is that while it’s topic-based and structured authoring, all the things you create are either books or sub-books. I wonder if that interface could be changed to refer to deliverables or some other such generic term that isn’t loaded with a print connotation. It’s a minor nit to pick, that the loaded term “book” is so prevalent, but many other editors and CMSes have gone beyond the book terminology so I was surprised it still lives in AuthorIT.

To be perfectly honest, I wasn’t all that impressed with the available outputs. Here’s the list from the AuthorIT website: (hey, I would have given you all a more precise link, but when I clicked Publishable Outputs in the sidebar in that page, I got a page not found error using IE 7 on WinXP SP2.)

Publishable Outputs

Print

• Printed Documentation (Word, RTF, or PDF)

Help

• WinHelp
• Microsoft HTML Help
• Sun JavaHelp
• Oracle Help for Java
• Vista Help (Upon Release)

Web

• Web and browser based Help
• HTML 4.01 + CSS (W3C Validated)
• XHTML 1.0 + CSS (W3C Validated)

Presentation

• HTML based slide show Presentations

XML

• XML
• DITA

The first omission that comes to mind is the lack of Eclipse help output. There’s also no Flash help output. In addition, I wanted to analyze further on the usability and look and feel of the Web and browser based help, especially with the recent article complaining about DITA’s lack of a cross-browser “Web help” like what Robohelp outputs as well as the lack of FlashHelp output. There are a couple of good articles out lately about it. There’s an article on ditausers.org comparing Help Authoring Toolkits to the DITA Open Toolkit. His output comparison matrix for DITA points out the lack of a webhelp equivalent for DITA Open Toolkit transforms. Here’s Tony Self’s recent analysis on Writer’s UA website. But I’m not talking about DITA necessarily, unless I was going to propose outputting AuthorIT to DITA and using DITA transforms for publishing, a workflow that I’m not proposing because it just seems too roundabout and more difficult to automate.

Anyway, my first glance at the AuthorIT web help output is that it’s a little bit antiquated but it is tripane and it does have contents and index tabs but no search tab according to the demo on the AuthorIT site. Frankly, without a search function, no help system is complete. With a quick Google search, though, I learned from Char James-Tanny that “by default, AuthorIT does not include a search tab, although the Help file does include instructions for hooking up a free CGI search.” That article appears to be dated January 2003 so I would have to do more hands-on testing to determine the quality of the search and the ease to implement it. Interestingly, in that article she mentions using AuthorIT as the CMS and editing environment and then using RoboHelp for the more feature-rich output engine. I wonder if that’s still a viable toolkit and publishing engine combination now that Adobe is developing RoboHelp.

Writing an article like this one while I’m still very inexperienced with AuthorIT is risky because I will read it later and think, “why would I proclaim my ignorance in a public manner?” But I believe it’s important to capture initial thoughts and reactions while they’re fresh in my mind. So bear with me while I analzye the authoring system and the publishing system and draw some perhaps premature or immature conclusions.

This article was original published in the June 2007 issue of the CIDM Best Practices Newsletter. It is re-published in its entirety with the permission of the Center for Information Development Management.

In this article, we examine an increasingly popular development methodology from the Extreme Programming family—Agile development—and how technical writers can operate successfully in this methodology. We answer the first questions technical writers might ask when assigned to an Agile team:

• What is Agile development?
• How does Agile development affect my role on the team?
• What are the best methods for succeeding as a team member with this software-development methodology?

The experiences we discuss come from using Agile and a related methodology, Scrum, in creating enterprise software, like database administration tools, rather than Internet applications like Yahoo! Photos. This distinction is necessary because of the vast differences in the length of release cycles; enterprise software teams deliver in three to nine month cycles, while some Internet software teams deliver in cycles as short as two weeks. These differences mean that the implementation of Agile development varies greatly. Now, let’s look at some guiding principles of Agile development.

Agile Development Defined

The main principle of Agile development is to develop robust software rapidly with minimal expense and investment in detailed, up-front design. “Robust” and “rapid” are manifested in the use of iterations, or short development cycles (usually 2–3 weeks), in which a particular piece of the software is developed, tested, and documented. A development cycle built on iterations allows for rapid and continuous delivery, and it provides agility and flexibility that are missing in more traditional development methodologies. Problems are quickly discovered, and teams can either immediately correct a problem or eliminate an affected feature altogether without wasting design work that would have occurred in traditional methodologies, such as waterfall.

The Agile methodology is part of a large family of development processes and has no single, prescribed method. Many companies create their own Agile methods while using some of the original ideas and principles defined in the Agile Manifesto (http://www.agilemanifesto.org/).

A basic tenet of Agile methodologies is “Working software over comprehensive documentation,” meaning that internal design and specification documents are minimal or non-existent. Many technical writers struggle to be fully functional in such a development environment. Writers have traditionally relied on design documents to get a “big picture” of the product—what it does and how it works. The amount of internal documentation varies widely among Agile teams. Some teams do not even produce a list of product features, relying instead on their Agile planning software to act as a repository of the list of stories and tasks to be accomplished in each iteration.

Another tenet of Agile, “Individuals and interactions over processes and tools,” can make writers feel marginalized when determining how best to function in the team. Fortunately, the best Agile teams understand the value of end-user documentation or can be shown that an integral part of creating successful, working software is excellent documentation written in a tightly collaborative environment. In such an environment, the technical writer can adapt and even shine.

The Language of Agile Development

Often the most intimidating part of learning anything new is grappling with a new vocabulary, and Agile is no exception. Following are some basic terms that are used frequently in Agile teams:

• Iteration: A period of time during which the software is programmed and at the end of which the quality assurance (QA) testers verify that the software is working as expected.
• Stand-up: A daily meeting in which the progress of the software development is communicated.
• Story: The business need that defines what the software will do for the user. Stories are usually sized so that a single iteration is enough time for development, and they are usually written as “role can do task” (for example, “An Administrator can add a new User”).
• Task: Defines all of the subtasks for a single story. For example, for the story “An Administrator can add a new User,” one of the tasks might be “Connect the new component to an existing security component.”
• Backlog: A repository for stories that are targeted for release during an iteration.

How Does Agile Affect Your Role and Processes?

As part of an Agile team, you are expected to tell the team what you will deliver at the end of an iteration. Working in iterations has a definite affect on the scope, content, and presentation of your deliverables. You must be prepared to communicate your status daily because many Agile teams track progress on all stories and tasks daily.

Some techniques and certain deliverables are well suited for documenting products that are developed in an Agile environment:

• using a topic-oriented approach such as the Darwin Information Typing Architecture (DITA) or Information Mapping^TM
• leveraging user stories to produce task-oriented documentation
• applying minimalist principles
• participating as an active team member

Topic-oriented writing

Most writers are familiar with topic-oriented writing: authoring concise, self-contained units of information about a specific topic. Topic-oriented writing is a defining aspect of Information Mapping and DITA. In Information Mapping, complex information is broken down into basic components, and then the “chunks” of information are structured in a reader-friendly way. In DITA, information is categorized into concept, task, and reference topics. Such categorization makes sense in an Agile environment, in which “the right documentation at the right time” is the main goal for all documentation, end-user and internal.

In addition, DITA maps offer just-in-time assembly and output generation of documentation, which provides a huge advantage when creating Agile documentation. In an Agile environment, changes that make the software better, even at the end of an iteration, are welcomed and encouraged. But if a new function is eliminated from an iteration after you have already documented it, you just remove those topics from the DITA map for that iteration’s build. Keep those topics for the next time that feature is worked into a user story, and you become the hero when you link those topics in a new DITA map and generate output.

Translating User Stories into Task-Oriented Topics

In an Agile environment, development is driven by user stories, which define the tasks that end-users want to accomplish with the software. User stories must be customer-focused, succinct, and testable, and writers can leverage them to create user-focused, task-oriented documentation.

Task-oriented writing not only complements development’s use of user stories, but it is an absolute necessity given short iteration cycles and an often limited number of writing resources. The requirement to create installation and configuration information and solid procedural information (probably in an online Help system) often leaves little time in any release cycle to create much conceptual or best practices information. Such information can, however, be produced following a particular release cycle. The focus on tasks within a cycle, however, helps writers achieve minimalism, another technique particularly well-suited to documenting in an Agile environment.

Just-In-Time Documentation Also Means Just Enough

Minimalism in technical documentation has been advocated since IBM’s John Carroll wrote The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill in 1990. Minimalist principles are especially relevant when you adapt Agile methods to produce working documentation that complements working software at the end of short iterations. For example, you should avoid wordy overviews that are not task-based, and you should not even document obvious procedures such as how to cut and paste text or print reports.

The Importance of Team Spirit

Being an active member of the Agile team is crucial to a writer’s success. The lack of internal documentation makes full participation in the team an absolute necessity. Your awareness of hallway conversations and impromptu white board drawings about changes to the GUI, for example, could mean the difference between completing your stories or tasks within the specified iteration or not. The need for such camaraderie obviously must be understood and embraced by the developers and testers on your team.

Ideas for Best Practices

Having survived and thrived during releases using Agile methods, we have a few ideas for best practices, as well as pitfalls to avoid:

• You will be most successful if you are dedicated to a single Agile team, not a resource shared by several Agile teams. This focus enables you to attend all meetings, like the daily stand-up, where you can gather information and overcome roadblocks.
• Encourage and embrace the face-to-face communication that is a driving force in Agile.
• Locate your workspace near your developer and QA teammates if possible. If you cannot work physically near your Agile team, find ways to communicate as personally as possible in real-time, such as using Instant Messaging or web cameras with video conferencing.
• Agree with your development team on two key points:1. should the documentation tasks be included in the development team’s story or housed under a separate, documentation-specific story?
  2. how many iterations can the end-user documentation lag behind the development team’s completion of a feature?
• Write user stories for documentation that parallel the user stories that are being used to build product features. An example user story for documentation might be “A DBA can read online Help to learn how to manage licenses.” An alternative is to create documentation-specific tasks that are included under the development team’s user stories. For example, the development team might have already created a story called “A DBA can manage licenses”; as the writer, you can simply add a documentation task to the story. Another idea is to house all documentation stories and tasks under a parallel project, so that you can easily estimate documentation’s velocity.
• You must have access to the same planning tool that the Agile development team is using. This tool may be software based, such as Rally or XPlanner, or it may be index cards on a cork board. The ability to create entries gives the documentation tasks equal visibility and footing with development and QA tasks related to each user story. In some environments, the planning tool is the only place to see a comprehensive list of the product’s planned functionality, as represented by the stories.
• Request that all user stories be stored and accurately maintained in a single place, which will most likely be the Agile planning software. Ideally, the product manager or development team creates a product feature list or some document that states all of the product functionality.
• Write a minimal documentation plan so that you can focus on story planning and end-user deliverables. The documentation plan could list the key contacts, release theme, top stories, dates, and your expectations and assumptions.
• For each user story, ask the QA team to create an equivalent task for reviewing the online Help or other documentation.
• Request a “hardening” iteration in which you can complete final tasks for your deliverables—for example, check index entries on final assemblies or determine the optimal organization for a table of contents. Final user stories for documentation might end up in a “hardening iteration” that includes technical reviews.
• Use the backlog to house documentation tasks. First, pull high-priority, low risk items from the backlog into an iteration, and then return to the backlog for lower-priority or higher-risk items in another iteration.
• Keep your documentation task-oriented, in line with the user stories that are promised with each iteration. If you want to take task orientation to the next logical level, write your end-user documentation in a topic-oriented way with tasks having supporting concepts and reference topics, much like the DITA prescription.

Conclusion

Just as programmers employ Agile techniques to improve their deliverables, technical writers can employ complementary writing techniques to become an integral part of delivering useful software. End-user deliverables that are task-oriented and help the user perform at an expert level become a necessary and valued part of the success of a product developed using Agile methods.

Bibliography

Beck, et al., Manifesto for Agile Software Development http://www.agilemanifesto.org

Broderick, Stacia and Melody Locke. “A Tale of Two Writing Teams.” agile, pp. 295-304, AGILE 2006 (AGILE’06), 2006.

Cohn, Mike. Agile Estimating and Planning Prentice Hall PTR, 2005

About the Authors

Tana Berry
Senior Technical Writer
Database-Brothers, Inc.
tana.berry@database-brothers.com
Tana works as the only technical writer at Database-Brothers, a small company with a focus on database auditing and performance products. She has enjoyed working as a technical writer for more than twelve years and has been an active team member on an Agile team for a year. Tana loves Agile because it forces the writer to produce lean, task-oriented documentation with the end-user always kept as the focus.

Anne Gentle
Senior Technical Writer
BMC Software
anne_gentle@bmc.com
http://talk.bmc.com/blogs/anne-gentle
Anne Gentle works at BMC Software where she writes technical deliverables ranging from user manuals to online help to white papers. BMC has many product lines adopting Agile development methods and the product Anne now writes for, Configuration Management, has recently become Agile. Known to enthusiastically discuss communication topics ranging from blogging to wikis to XML-based information models like DITA, she sees DITA as an excellent gateway to more Agile documentation.

In a planning meeting for creating our new topic-oriented workflows and processes as Agile user stories, we created a persona for what my role could be as a “Designer” of a new way to write information. Say, that’s me! It was entertaining to read about my persona. I share it with you in an attempt to describe what an information designer or architect role may be like. We’re using personae as a means to gather requirements for new tools and infrastructure for topic authoring with DITA. So here goes:

Designer - Let’s call her “Denise.”

She is an experienced writer, has likely been at BMC longer than 5 years. She’s independent so she might be hard to manage. (editor’s note: I beg to differ!) She’s your “Guru” writer, a leader/advocate/evangelist and power user. She’s an early adopter of most all technology and DITA and XML knowledgeable. She’s quite knowledgeable about the BMC infrastructure related to tech pubs. She likely has some lightweight development skills such as scripting and is tool-savvy. She’s innovation-focused, always looking for technology improvements, and a big picture person, which makes her process driven and organized.

Yes, indeed, I resemble that persona. And I didn’t even write this persona, a group of IT folks and writers wrote this persona. Very interesting to have a mirror of yourself written down, but boy, do I resemble these remarks.

XML editor evaluations related to DITA

We’re evaluating software tools for XML authoring and use cases and persona are a great way to start looking at how the future of techpubs will shape itself. It’s a similar approach to the authoring scenarios that Don Day advocates when evaluating DITA editors. I’ll write a few use cases that we’re considering for authors in another blog entry so stay tuned if you’re interested in evaluation methods for software programs.