just write click

I’ve had a very serendipitous journey lately based on my podcast on TechWriterVoices and the work on the One Laptop Per Child project that I want to share. Through others listening to the podcast, hearing about OLPC, and contacting me via my blog, I learned about wikislices, and it just might be a method for DITA and wiki to play in the same sandbox.

This concept seems very apropos to the shift we’re seeing in technical publications away from books. What’s interesting is that there seems to be two directions you can go from books - wikis or DITA, crowdsourcing or singlesourcing. Some times it seems like choosing between wikis and DITA is like new school/kewl kidz versus old school/squares.

But what if there’s a way to have your wiki be the single source (also crowd sourced but with a strong guiding hand, let’s say), but to create cross-sections or wikislices of that content? This idea would essentially allow writers to write in the wiki and then either the writer or an architect would “slice” it.

There is a way to Wikislice Wikipedia already. Go to wikislice.webaroo.com and enter a subject. You can view this nice slideshow showing the basic features of a wikislice. You can even make offline wikislices available.

There are selected wikislices created already for the One Laptop Per Child project, such as the Great Wall of China, Space exploration, and the Brothers Grimm.

What’s interesting to note is that the Webaroo wikislice of “violin” is different from the one for the OLPC wikislice of “violin” and it appears that the OLPC one is more easily read by a student. Somehow the slices are customized, perhaps for the audience? I’d like to dig deeper into the guts of a wikislice. All I’ve found so far is that they’re built using regular expressions according to the Wikislices definition on the OLPC Wiki.

With the correct use of tagging in your wiki, I would imagine that you could slice the wiki based on audience, language, or content type, such as grouping tasks, reference, or concepts.

It seems like any wiki could be wikisliced, and if DITA maps are the method for the slicing, then you can get a table of contents and PDF output based on a cross-section of your wiki - a wikislice. This process is just a thought piece right now, but my hope is that working on the OLPC project helps perfect the wikislicing process so that it could be used for other end-user documentation projects.

It was one of those light-bulb-type discussions. Ideas popping and synapses firing. I had lunch with Chris Almond and Don Day this past week, discussing the potential authoring of wiki articles using DITA. We went through possible workflows, from a web-based DITA editor - to authoring in another tool and merely using DITA as an intermediary and transforming to wikitext.

If you know about DITA, you recognize Don Day as the chair of the OASIS DITA Technical Committee. Our lunch companion was Chris Almond, an innovative forward-thinking project manager. From him, I got the sense that internally at IBM, there is a perception of DITA as a technical writer-only tool to have in your toolkit. Chris coordinates and manages the authoring of IBM’s RedBooks, a very popular and technical set of documentation that are not product documentation but rather they show users how to implement a specific set of products, integrated together. He’s coordinating teams to do the scenario-based writing that applies the product in real-world situations. Many techpubs teams are striving towards use cases and scenario writing, and RedBooks are a great model for how to do it well. I know we tried to emulate it at BMC Software, and Bill Gearhart has an article about “Scenarios and Minimalism” in the CIDM Newsletter that discusses scenario and case study authoring.

Chris is trying to figure out how their current writing methodology and processes can be protected but also enhance the tools used and improve the resulting connections after the deliverable is written. Currently they engage with teams of authors to outline scenarios using mindmapping software and then divide up the actual writing assignments according to the author’s experience with the scenario. I immediately thought of JoAnn Hackos’ and Dan Ortega’s suggestions to have field personnel contribute scenarios to a product’s wiki when Chris described their process.

How do you actually empower the teams to write these wiki articles and assemble them into a useful (maybe book-like) wiki? Another question to Chris was, how do you layer an outline or table of contents on to the wiki, and then test and fold in any changes that wiki contributors make?

After at least an hour discussion I’m not sure we ever came up with the correct toolset. Or rather, there was a toolchain that could be used which is certainly do-able but not the ideal that he wanted to get to. I suppose one ideal is a DITA-based wiki with a web editor interface that would change editor strictness based on the author’s permissions. Authors who knew DITA and were most comfortable writing structured tasks, reference, and concept topics would get an XML-validating editor and authors that preferred more free-form would just use a rich-text editor that was nothing more than HTML headings, paragraphs, and lists underneath like what you use in Drupal, WordPress, or Blogger.

Suddenly it became apparent to me (but I won’t and don’t speak for Chris and Don) that some people are more determined to keep the editing quick and easy, but sacrifice that structuring and vetting step that structured authoring gives you.

This realization gives me a sense that 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. Also, the types of information that these authors are trying to capture are opposed in some senses. Then I thought a diagram might help.

wiki-fast-easy <-----------+-----------> DITA-difficult-tested

high-level scenarios <-----+-----> detailed dialog boxes

With such an easily diagrammed moment, you’d think I’d have an answer for the process we could use for a DITA-based wiki. Unfortunately it’s not quite refined, but I feel a step closer to understanding why this process is difficult to create - because the process is paved with these tradeoffs and apparent compromises and decisions you have to make along the way.

I’ve been looking at content at BMC and determining whether it belongs in a concept, reference, or task topic using DITA’s definition of a topic. I had one particular item that seemed like it could be arranged in several different ways with advantages and disadvantages for each method. I had a great conversation with a fellow writer and a technical editor in the car on the way back from our corporate offices in Houston, and I thought I’d capture that discussion in a blog entry. So here goes.

Background information for this task

Overall, the user wants to configure their shiny new BMC Performance Manager for Databases product. It’s a pretty flexible configuration process to accommodate the needs of different environments but also to balance out ease of installation and configuration. So, you can either have the product automatically configure everything (you have to have certain user permissions on certain objects to do so) or you can manually configure by editing some included scripts that will give the correct permissions to each individual object (also requiring certain permissions but gives you the exact knowledge of what’s happening to your database).

So, as you might have guessed, the manual configuration goal turns out to be the toughest to turn into topics. I decided to look at the tasks related to manual configuration and then write the supporting topics.

What’s the task here?

But is the task itself “manually configuring” or is it “editing scripts?” I finally decided the task itself is editing the scripts, much to my chagrin because it doesn’t sound like a goal-oriented task. In addition, the background information for knowing why you’d do auto vs. manual should be explained in a concept topic, I believe.

But here’s where the decisions got a little tougher. The supporting reference information is a table of the objects and the required permissions on each. Obviously exactly the sort of information the DBA needs to know to get the job done. However, the complication occurs when I see this big table listing the script names — is that a second reference topic supporting the task of editing scripts? It’s only two columns but it’s a matrix of three supported databases with at least three script names for each. It’s essential information, required in order to complete the task of editing a script for manual configuration.

Do you put reference info in with the task if it’s critical for completing the task?

So do I keep that reference information with the task itself to avoid separating it into a standalone topic? Or assume the reader might come to that topic from many different directions so it should be by itself but in a related links link from the task.

Final decision - make it a topic

In the end, I decided that for ease of reuse and to offer multiple entry points to the information, I would make the script table standalone as a separate topic. It seems like the benefits are that the user can find that topic more easily and also that reference info can be related to other tasks as well. Other deliverables may also want to include that reference information so designing for re-use seems like a benefit here as well.

I’m still a little uneasy about my final decision to make four topics out of what is essentially one end-user goal — to manually configure their product. Does anyone who does topic authoring often have any suggestions?

Parting thoughts on the complexity of software documentation

This type of configuration complexity is why many examples in topic authoring presentations and articles ring hollow to me. Examples of the portability of telephone pole repair manuals and the task-orientation of cell phone manuals are not the types of concrete questions I ask myself every day when writing software doc. The classic example of “Hold the power button for 0.7 seconds” as a poor example of a step in a task immediately comes to mind. An equivalent software documentation example is much more complex than instructions for a task on a cell phone.

Software doc lives in the abstract. Instead of an easily known or recognizable metaphor, I’m faced with products that are increasingly flexible but that flexibility causes the user to be faced with many micro-decisions. I think it’s my responsibility to guide the user through their choices and offer the technical advice for them to make the best decision, no matter how they’ve approached the doc in the first place. (from a search engine? from the table of contents?) It isn’t easy but oddly enough I enjoy the hunt for the best content organization and chunking possible.

I attended the central Texas DITA users group meeting last night, and wanted to write up some notes. We had two speakers share their thoughts after attending two related conferences this spring.

Bob Beims from Freescale shared his thoughts on attending the DITA 2006 conference at North Carolina State in Raleigh, NC, the first conference of its kind. He thinks he heard there were 185 attendees, and was pleasantly surprised at the range of users he met there. People were from medical companies with products for nurses, from the financial industry, from power and electric companies, and there was the hardware and software crowd. He had a couple of great quotes from different sessions. How about: “This is not rocket science… it is really bow and arrow stuff that has been implemented with technology.” from Michael Priestly of IBM, or “there’s never enough time and money to do things right, but always enough time and money to do things twice!” from Bernard Aschwanden of Publishing Smarter. I personally liked “Take the leap (or fall off the cliff!)” from Bob himself.

Bob said he realized that DITA solves some topic orientation problems that our industry has faced for decades. He was pleased at the rate and pace at which the DITA Technical Committee is churning out releases… 1.1 due out soon, and 1.2 in the next nine months. He feels that the OASIS leadership proves that DITA is not “just an IBM thing.” He thinks DITA maps should be awarded innovation of the year. He said, if you hate the limitations of FrameMaker conditional text, you’ll love the future of DITA with key values ( DITA proposed feature #40) that would allow boolean queries against conditions for output. A conditional text tags contest ensued, with a starting bid of documents with 13 conditional text tags and finally someone with a Frame document with 39 conditional text markers won the contest. I appreciated his comments on the two strata of tools — either very expensive, very functional, and easy to use, or (almost) free, fairly functional, but you’d better be a gear head to use ‘em. He sees a definite lack in conversion helpers for legacy content. Of course, with those words, a lively discussion ensued about transforming content versus just getting the text out by converting. Nearly all those experienced in unstructured to structured conversion projects discover, a real human has to figure out how to make topics out of the text that comes from a conversion. People who had done conversions said that Perl on MIFs out of Frame does the trick for getting out text, but in some cases you’re better off starting from scratch to plan for reuse and true topic orientation. Still, a conversion script (or set of scripts) at least takes your existing text into a structured start. Bob also said that something he has learned while researching from many presentations inside and outside of the DITA conference is that you must develop an Information Architect role or you’ll end up chasing your tail when it comes to truly gaining benefit from a topic-oriented architecture for your information.

What does Bob see as next for DITA? He’d like to see a lower bar for entry. Currently the entry “fee” includes a lot of time for preparing your content and training your writers, skills necessary to participate are high, and there’s money required for a bat and ball. He thinks there can be integration with non-DITA XML information streams, especially for those who interface with manufacturing industries. His example from Freescales’ perspective was the RosettaNet effort, where hardware manufacturers can offer “product and detailed design information, including product change notices and product technical specifications” via XML specifications. Incorporating that with DITA topics would help them build their information deliverables. He also noted that the DITA community might be a small one, but it is definitely composed of bleeding edge technology and technologists.

Next, Paul Arellanes, an information architect at IBM, gave his impressions of the Content Management Strategies 2006 conference in San Francisco. He saw a definite eagerness to adopt and use the DITA Open ToolKit as well as eagerness to reuse, reuse, reuse. His talk, Taxonomy Creation and Subject Classification for DITA Topics was highly attended (standing room only) and very well received. He also stressed the importance of training on topic orientation before going to XML. He has a programming background, and likens DITA to object-oriented documentation. He’d like to see code reviews of how the tags are used and if they’re used correctly. He got a couple of good ideas at the conference for how to build code reviews into the document review cycle. I’ll talk about those in the next paragraph. Paul talked about reuse and asked if it’s a boon or a curse? Can you reuse a topic if you can’t find it? What if the topic was never designed for reuse in the first place? How can you design for reuse in the first place? He’d like some best practices for reuse.

He said that implementing DITA is a chance to change your documentation processes — going to topics with a fresh start at content is more successful than a legacy conversion due to being able to build and design for reuse. His takeaways are that we need best practices for reuse, he’d like to build in source code reviews, and found a cool method for doing that with an editor’s CSS process that checks syntax. These are the common errors that you could find and mark up with CSS (basically, colorcoding the output after running it through a syntax checker built on CSS). Often these types of syntax/markup errors happen because the writer is tagging for looks, not for meaning of the content, but it can also happen with legacy conversion.

• placement of index entries
• sections that should be separate topics
• use of definition lists to create sections
• ordered list tags instead of using step tags
• lists of parameters in ordered lit tags instead of param list
• use of unordered list tags with bold instead of definition list
• use of <ol> or <ul> instead of substeps or choices element in a task topic
• use of <filepath> for variables and terms
• menucascade not used
• uicontrol not used

Paul also has good ideas for the future, including a troubleshooting or problem analysis and determination specialization from the task topic, and perhaps a way to pull out DITA elements from a topic and plugging it into interactive content using AJAX. He was pleased to see that the skill set among attendees is pretty high, including XML, XSLT, SAX, FOP, CSS and Ant build tool skills.

Interestingly, as far as our group could see, Adobe was not represented at the DITA 2006 conference, even though they have a group implementing DITA for solutions documentation.

If you’re like me and didn’t attend the DITA 2006 conference, you might enjoy (as I did) the transcript of Norman Walsh’s talk. Norm is the chair of the DocBook Technical Committee, and DocBook and DITA are constantly pitted against each other for solving the problems of information developers.

JoAnn Hackos is well known in the technical writing community and is a member of the DITA Technical Committee. Recently she wrote the article asking, Is DITA Going to Tip? which explores Darwin Information Typing Architecture (DITA) in the context of an idea that will become widely accepted and popular as Malcolm Gladwell’s book The Tipping Point describes. She spoke at the Central Texas DITA User Group meeting held at BMC Software on January 25, 2006. This post contains a summary and notes from her talk. Our technical editor, Kelly Holcomb, took better notes than me, so I’m borrowing heavily from her notes for this post. Thanks Kelly!

Books

JoAnn’s entry point for talking about DITA and structured authoring was the transition from writing books to writing topics. She stressed the necessary paradigm shift for writers away from thinking about what they do as writing books to thinking about what they do as writing essential, correct, easily accessible, and easily digestible content that users need to perform their tasks, meet their goals, get their work done, and be home by 5 P.M. That’s everyone’s goal when using technology, hoping it will help you get something done faster to free up time for other things.

She leads us out of the book model by stressing that manuals are not books—users don’t “read” them from the first page to the last like we usually think of reading a book. They use manuals to look up necessary information. Users are not readers!

She talked about our manuals being an outgrowth from the publishing industry, and of the excitement in the profession, years ago, of being able to produce information that was actually attractive. But the influence of desktop publishing has been detrimental because we have gotten so caught up in how the information looks (formatting, sticking to a “book” structure, marrying format to function) that we tend to overlook the real needs to the users. And, all the attention to formatting detracts from what we actually do as technical communicators (the perception of outsiders of what we do has been adversely affected).

She actually held up the “About this book” type of section as an example of an artifact of publishing with no real use for our users.

So, what do customers require? Tell me if you agree, and I agree with her list:

• Task-oriented information for getting things done
• Minimalism: less info=no glut
• No out-of-date information stuck in books
• Information that is easier to find and easier to use

Topics and DITA

What are topics?

• Discrete units of information covering a specific subject with a specific intent
• Small enough to promote reuse across multiple contexts and output media
• Large enough to be easily authored and large enough to be readable and coherent
• Able to be organized into a wide variety of structure, from linear to networked

Topics allow us to provide “just enough” information to the users. Writing topics removes the interconnectedness of books and lets information stand alone. Context is not provided by a super-structure (the linear structure of the “book”), but from within the topic itself by its complete, discrete information and links to related information.

DITA supports topics through its model of concept, task, and reference topics.

Specializations in DITA help the designers communicate with the authors about what kind of information they are writing.

With DITA, writers create maps. “Maps” are what our users need—a way to get into and through the information. She talked about getting away from the straightjacket of the PDF into an information-centric web site (her vision). Such a web site allows the users to find the information they need, and find other related information. She stressed the relationships of topics: providing access to related information or prerequisite information, and letting users give feedback about what other information might be relevant to a particular topic (suggesting other related info links). She also talked about unnecessary concepts: if you can’t relate a concept to a task that the user must perform, you should question the appropriateness and relevance of providing the concept in the documentation.

Planning topics

She stressed the idea that effective topic-oriented writing requires planning and collaboration, especially if information will be produced by many writers. The lack of collaboration has traditionally led to duplication of information, as well as gaps of information, in books.

• Begin with tasks that users must perform to reach their goals
• Consider possible scenarios that illustrate typical user tasks in the context of real-life goals
• Turn basic tasks into introductory tutorials

She used the AutoCAD documentation as a good example of providing brief tutorials for basic tasks (as AutoCAD users said, “teach us something in 10 minutes”). Then, she showed us how they augment the tasks/tutorials with conceptual information, often provided as videos. Then they add the reference information that is needed to support goals (their online reference command). This online Help/document provided three tabs at the top of the right-hand pane (the information pane). These tabs provide access to tasks, concepts, and reference information related to the current information.

Business case for topics

• Topics promote minimalist agenda—fewer words to manage
• Topics promote structured, consistent writing
• Topics are easier to localize, further reducing costs
• Topics enable multiple deliverables to meet the needs of diverse user communities

Manuals are tools that must be fitted to use; topics make manuals economically possible. Her story illustrating this point tells of a telephone repair technician who had to take not one but three snowmobile trips in order to repair a remote station. He didn’t lug a 500-page manual with him, as you can imagine.

Guidelines for topic-oriented writing

• Focus on best practices in information design (as always)
• Don’t construct elements for every bad design decision. In other words, don’t change the standards to fit your current content, but rather make your content conform to the standards
• Develop authoring standards and guidelines, and provide example for writers
• Demonstrate how to apply DITA elements correctly. Part of the editing process needs to look at the tags to ensure that they are used correctly. Incorrect use of tags will make reuse impossible.
• TRANSFORM information, don’t convert it!
• Use the transformation to harmonize topics and identify levels of reuse.

Information that came up in relation to questions asked by audience

I asked a question about the approach to implementing structured authoring, specifically analyzing content and creating models/specializations from that versus transforming information to fit in the standards and model. JoAnn’s advice: Look for the DNA of the information, the underlying structure that governs the information. Don’t try to squeeze every idiosyncrasy and every construction error ever made into the new model (transform, don’t convert).

Another audience member asked about the relationship between information mapping and DITA. They have practically identical philosophies; information mapping provides more types of information than DITA (7 versus 3), and information mapping has more to say about how information is developed, but in JoAnn’s opinion, the two methods are highly compatible. (She mentioned that the Information Mapping organization has just announced their support of DITA.)

Don Day or JoAnn also mentioned Michael Priestley’s article about scenario-based writing, which sounded interesting (illustrating a different way of approaching the content). Here’s a link to the presentation slides and article on xml.coverpages.org (Thanks, Don!) or if you’re an ACM member, here’s a link to a PDF download. http://portal.acm.org/citation.cfm?doid=944879.

Later, in a separate discussion, Kelly and I talked with Don Day about how the needs (habits) of mainframe users are unique: they love their books and have special rooms dedicated to documentation. IBM should know about those users! So, the delivery of the information is still traditional for mainframe products.

Feel free to comment on your thoughts on the meeting or the ideas presented here. I’m definitely interested in how you read manuals (or don’t read them).

I’m off for a two week break and I’ll blog when I return. In the meantime, I’m reading about structured blogging.

I’ll be off next week for the holidays. The first week of January I’ll be welcoming a new niece or nephew to the extended family. Nope, they haven’t learned the gender, but we haven’t broken into the store where they’ve registered to find out, either.
Until January, I’ll share a post about structured blogging that I found in Charlie Wood’s blog about RSS in the enterprise, Moonwatcher. I’m contemplating an insightful post by Joshua Porter, ” Structured blogging, who is benefitting and how” and also learning more about the semantic web. I’m working on a DITA specialization for blog entries and I need to find out what elements the structured blogging folks will require. I’d like more practice in structured authoring using DITA, and since I’m writing two blog posts a week, seems like it’s the perfect opportunity to put get some structured authoring practice.
Happy holidays, everyone!