Exploring Information Design and Development

Known to write a script or two to automate repetitive tasks like help builds, she also likes to write posts about XML-based information models like Darwin Information Typing Architecture (DITA). She often experiments with online help technology, enjoys writing blog entries, and wants to find new ways to use communication to help people understand technical solutions to complex problems.

Gentle, Anne. BMC Software (2007). Resources>Information Design>Documentation>Blogs

Integrating Partner Information Using XML and XSL  

BMC Software Inc., a company that writes utility tools for database administrators, wanted to reuse the error messages from partner database companies. Having learned that two of these database companies already used single-source files for their error messages, BMC Software integrated the information about the error messages from the database companies. We accomplished our goal by negotiating with our partner companies for the source files of the error message information. This session discusses how we took those source files and modified them to create simple XML files, then transformed them into HTML using XSL transforms within a product.

Gentle, Anne. STC Proceedings (2004). Articles>Information Design>XML>XSL

Integrating Partner Information Using XML and XSL

Having learned that two of these database companies already used single-source files for their error messages, BMC Software integrated the information about the error messages from the database companies. We accomplished our goal by negotiating with our partner companies for the source files of the error message information. This session discusses how we took those source files and modified them to create simple XML files, then transformed them into HTML using XSL transforms within a BMC Software product.

Gentle, Anne. WritersUA (2006). Articles>Documentation>XML>Case Studies

Just Write Click

A blog about technical writing, information architecture, topic authoring, social media, and other technologies that catch Anne Gentle's eye.

Gentle, Anne. Just Write Click. Resources>Writing>Technical Writing>Blogs

Darwin Information Typing Architecture (DITA) Reading List

Here’s a reading list for DITA materials when you’re just getting started. I’ve been fielding some questions via email and IM about DITA lately, and pulled this blog post out of my drafts. I hope it’s helpful.

Gentle, Anne. Just Write Click (2008). Articles>Bibliographies>XML>DITA

Getting Started with DITA

A brief overview for a couple of fellow Austin writers who have asked me recently how and where to get started with DITA.

Gentle, Anne. Just Write Click (2007). Articles>Information Design>XML>DITA

Building a DITA-Wiki Hybrid  

Learn about theoretical and practical examples of merging DITA (Darwin Information Typing Architecture), a structured authoring methodology, and wiki’s freeform authoring and editing capabilities.

Gentle, Anne and Lisa Dyer. Intercom (2008). Articles>Documentation>Technical Writing>Wikis

The "Quick Web" for Technical Documentation  

So how did the wiki become a seemingly permanent fixture in the landscape of today’s Web? Which wikis have succeeded as technical documentation, and how can we replicate their success?

Gentle, Anne. Intercom (2007). Articles>Documentation>Technical Writing>Wikis

Embracing the Un: When the Community Runs the Event    

With the explosion of Web 2.0 come two new kinds of community events: BarCamps and BookSprints. Gentle and Swisher share their experiences with these unconferences.

Gentle, Anne and Janet Swisher. Intercom (2009). Articles>TC>Community Building>Social Networking

DITA and Wiki Combo

What are your thoughts on whether wikis could be used for end-user technical documentation? I'd imagine that a more structured wiki based on DITA content (which may have already been created for end-users) might work well for technical documentation. Have you seen any good examples? I'd love to see a well-done example.

Gentle, Anne. BMC Software (2008). Articles>Content Management>Wikis>DITA

Are Structured Authoring and Wiki Opposing Forces?

There are two camps in technical documentation. There’s the “quick web” folks who connect easily and author easily, and then there’s the “structured quality” camp that requires more thoughtful testing and time spent on task analysis and information architecture.

Gentle, Anne. Just Write Click (2007). Articles>Content Management>Information Design>Wikis

Now You Can Take That Blog Vacation You’ve Been Planning

How do you get fresh blog content even if you want a break, say a summer off of the routine of writing two posts a week? In this guest post, Anne Gentle discusses just that. The short answer? By tapping into your community or writing ahead.

Gentle, Anne. DMN Communications (2009). Articles>Writing>Blogging

Community and Documentation  

This chapter explores the idea that a small group of people who have a sense of belonging in an online community may provide content much like a technical writer does. Regardless of their background, education, or training, more people are becoming providers of technical information on the web.

Gentle, Anne. XML Press (2009). Articles>Documentation>Content Management>Social Networking

Corporate Collaborative Authoring

The idea of a Book Sprint is that you can get lots of documentation written in a focused amount of time with the right team and some amount of content already in place. Gathering people in the same room when possible is extremely helpful and motivating as well.

Gentle, Anne. Just Write Click (2009). Articles>Collaboration>Agile>Documentation

Choosing a License for Sharing Documentation Content

What issues and legalities do we as Technical Communicators or Wiki Administrators need to be aware of as we move towards collaborative authoring projects and so forth, especially when documenting open source software?

Gentle, Anne. Just Write Click (2009). Articles>Documentation>Intellectual Property>Open Source

Content Curation: A Manifesto

A Content Curator is someone who continually finds, groups, organizes and shares the best and most relevant content on a specific issue online. I think that professional writers and technical writers should consider a move towards this role. We already search for and find the best content, sift through loads of content, discard poor content, and publish the most worthy content whenever a software release goes out. This description also sounds like something a content strategist would do as part of their analysis of the content.

Gentle, Anne. Just Write Click (2009). Articles>Content Management>Information Design>Technical Writing

Tragedy of the Commons

You still have to be willing to moderate comments when you are a blogger or a wiki administrator. And you have to be willing to work hard to build a community that uses the technology in a productive way.

Gentle, Anne. Just Write Click (2009). Articles>Web Design>Community Building>Social Networking

Wiki as Forum, FAQ, HTML Editor, XML Editor, or CMS?

A wiki can be a Frequently Asked Questions repository, much like the knowledge bases in their heyday in the late 80s. My favorite line from the blog entry has to be its closer: 'It's about a different way of thinking around how to interact with the community.' And that is what I have explored with my wiki presentation, about how to build community with a wiki and be an active member of that community. But what are other uses of the wiki?

Gentle, Anne. Just Write Click (2007). Articles>Documentation>Content Management>Wikis

Twitter and Conversation Analysis: Who's Here?

I believe that phone conversations for customer support have been studied quite a bit -- looking for phrases that sound like triggers for anger, avoiding long pauses, and when one party overtakes a phone conversation, it's relatively easy to detect when that's happening. But with Twitter, you could have long pauses intentionally as asynchronous, IM-like conversations happen when someone gets up from their desk and returns after a business meeting, for example. Neither party is angry about that long pause, it's just an understood agreement in the Twitter medium that you may or may not be immediately responsive. How does that time factor change the 'agreement' for a support exchange?

Gentle, Anne. Just Write Click (2009). Articles>Collaboration>Social Networking>Help

Consistency and Community-Generated Content

I’ve been collecting examples of wildly inconsistent writing lately. I’m not sure why these have stuck out to me, but when I think of book sprints and community writing events, consistency is an important, though sometimes difficult, goal and outcome.

Gentle, Anne and Janet Swisher. Just Write Click (2009). Articles>Documentation>Style Guides>Wikis

There’s No Crying in Agile!

When I’ve read Agile practitioner reports that tell tales of times when technical writers have left meetings and fled to cry, I am not just surprised but a little dismayed.

Gentle, Anne. Just Write Click (2009). Articles>Collaboration>Agile