Random thoughts about publishing

icon Site Feed

Labels

Palimpsest has moved. Please visit our blog in its new location for the most recent posts from Scriptorium.

Palimpsest

 

Structured authoring in technical communication

Monday, April 27, 2009 — posted by Sarah O'Keefe

I am pleased to announce the publication of our newest white paper, The State of Structured Authoring in Technical Communication. In early 2009, we conducted a survey on structured authoring; this document presents the results of the survey along with our analysis.

Those who participated in the survey are entitled to a free copy of the report. If you requested a copy via email, you will receive a message within the next 2 business days with download instructions. If you requested a printed copy, those will go in the mail tomorrow.

The report is also available for purchase and immediate download. The cost is $200 for the 38-page report (plus 18 pages that reproduce the survey questions, so the file is 56 pages long).

I'm also delivering a presentation at next week's STC Summit in Atlanta, which discusses the results of the survey. If you're attending the conference, I hope you'll join me on Monday, May 5, from 1:30 to 2:30 p.m. in Regency V for "The State of Structure."

Labels: , , , , ,


5:00 PM Permalink | |

divider

 

Mechanical versus digital publishing

Thursday, January 08, 2009 — posted by Sarah O'Keefe

My last XML Strategist article (PDF) briefly mentioned Gutenberg and movable type before moving on to the focus of the article--a discussion of the implications of XML publishing and the similarities with Gutenberg's efforts. The Biblical Illuminator's Guild blog provides a much more detailed discussion of the technical challenges solved in production of the Gutenberg Bible, including:
Printer's ink. Gutenberg had to develop a new kind of ink, an oil-based one (as over against the traditional water-based ink used in manuscripts), so that it would stick better to the metal types. [...]

Font. The first part of the Gutenberg idea was using a single, hand-carved character to create identical copies of itself. Cutting a single letter could take a craftsman a day of work. A single page taking 2500 letters, crafting per page was unattainable. A less labor intensive method of reproduction was needed. Copies were produced by stamping the original into a iron plate, called a matrix. A rectangular tube was then connected to the matrix, creating a container in which molten lead could be poured. Once cooled, the solid lead form was released from the tube. The end result was a rectangular block of lead with the form of the desired character protruding from the end. This piece of type could be put in a line, facing up, with other pieces of type. These lines were arranged to form blocks of text, which could be inked and pressed against paper, transferring the desired text to the paper. Each unique character requires a master piece of type in order to be replicated. Given that each letter has uppercase and lowercase forms, and the number of various punctuation marks and ligatures (e.g. the sequence 'fi' combined in one character, commonly used in writing) the Gutenberg Bible needed a set of 290 master characters.
Read the whole thing. I think for many of us, the physical process of printing is a complete abstraction, except for the occasional toner cartridge replacement.

Contrast that with a recent article on Read/Write Web by Alex Isold, Brave New World: More Digital, Less Physical:
The main thing we learned is patterns in physical objects. We know that we can bend them under certain conditions. We know that there is friction. We know that things react differently to heat. [...] These patterns get wired into our brains and help us live our daily lives.

Computers have software inside that does not behave like physical objects do. The key thing about software is [...] that the conventional laws of physics do not apply to it. [...] It is hard for people with brains trained to deal with physical things to understand how software works.

[...]

Our kids are growing up native to this new digital world. To them, the new rules of digital physics are what the rules of physical physics are to us. They take these new rules for granted, because that is just how all our brains work.
And this interesting note in comment #20:
Your comments about how software has been designed to replicate physical effects, such as the bounce in the iPhone, are an indication that we need our software to conform to the way we see the world, not that we are beginning to conform to a new paradigm of software.
Like many of you, I grudgingly operate a Parental Technical Support hotline. My four-year-old is better at operating computers than her grandparents -- probably because she's never existed in a world without computers. For her, computers are obvious.

Now, if we look at the world of publishing, we are currently in the midst of an enormous paradigm shift. More than 1000 years ago, we replaced scrolls with books. Since then, we have been operating with books. The process of creating books has evolved from hand-copying to printing to desktop publishing, but the books themselves haven't changed much. (I did find it interesting that the Gutenberg Bible does not have page numbers. Those came along later in the sixteenth century, according to this article.) Books are obvious. We've been using them all our lives and so have our parents, grandparents, and ancestors.

In the 1980s, we shifted from mechanical production (cut and paste, galleys, etc.) to computer-based production (desktop publishing). Again, the process of creating books changed, but the end result was still a book. (Perhaps a book with horrid layout and ransom-note fonts, but that's a discussion for another day.)

And this brings me to the challenges we face today. In addition to another paradigm shift in publishing -- this time from desktop publishing to structured authoring -- we have a second, more fundamental shift. In addition to (or perhaps instead of) producing books, we must now produce digital information -- online help, wikis, forums, email, databases, and much more. We don't have hundreds of years of collective experience to draw upon in figuring out how digital information should work.

Thus, we see efforts to fall back on the book paradigm. Just as computers have "desktops" and "folders" in an effort to make them more understandable, we have e-books with "pages" and "bookmarks."

What will truly digital publishing look like when we let go of the requirements of a paper book and embrace the possibilities of digital information fully?

Labels: , , ,


8:00 AM Permalink | |

divider

 

Surprise! It's about quality.

Tuesday, August 19, 2008 — posted by Sarah

(Scriptorium Publishing is a JustSystems Services Partner.)

On Monday, August 18, I delivered a webinar on making the transition from desktop publishing to structured authoring. This event was jointly sponsored by Scriptorium Publishing and JustSystems. The recorded version is available here (registration required).

During the presentation, we did some audience polling. And here, there were some surprises for me. We asked:

How are you authoring content today? (choose any)
Nothing too shocking here, although I was a little surprised to see such a high number for XML authoring in a session on how to transition to structure.

In poll 2, things got very interesting:

What is the level of authoring at your organization? (choose one)

9%, #1. Chaos. No consistency
4%, #2. Documents match on paper
16%, #2.5 We have a template and sometimes follow it.
60%, #3. Template-based authoring. Repeatable process for creating consistently formatted documents
10%, #4. Structured authoring. Programmatic enforcement of required organization

When I ask this question a roomful of people, it's rare to get an admission of level 1. I've never seen anything like 10 percent of a live audience choose number 1. Perhaps the relative anonymity of a webinar is a contributor?

We asked some questions about skillsets with nothing of particular interest to report. Finally, we inquired about the business driver for structure implementation:

What is your critical business driver behind looking to improve how you manage content?
(choose one main driver)

10%, Speed up time-to-market
30%, Improve satisfaction with customer-facing documentation
3%, Comply with regulatory requirements
12%, Reduce localization cost
27%, Improve staff productivity
13%, Reduce production cost
4%, Other

The surprise here was that, at least in this group, the most single common response was a quality answer ("improve satisfaction") rather than a cost-reduction answer.


My session was the first in a series of three webinars we are doing jointly with JustSystems. The next two sessions will focus on the DITA Open Toolkit. Simon Bate, Senior Technical Consultant with Scriptorium, will deliver an overview of the Open Toolkit on August 26 and a session on troubleshooting and customizing the Open Toolkit on September 23. The webinars are free, but advance registration is required here. Hope to see you there.

Labels: , , ,


11:27 PM Permalink | |

divider

 

STC UK...almost live, part 2...Managing change

Monday, June 23, 2008 — posted by Sarah

Ant Davey, Rail Standards Safety Board (RSSB)

Another excellent session. Ant provided a discussion of change management with quite a lot of references to more detailed resources.

Knowledge is being lost.
Information has value.
Web is changing search methods and expectations.
Web is changing ability to contribute and review content.

Findable information requires chunking.
Chunks are potentially reusable.
Ultimately, you have single sourcing.
Not "how we have always done it."

Chunking requires modular and collaborative writing.
Not "how we have always done it."

Single sourcing @ RSSB
* Still finding our way
* Technology led (in part)
* Starting to introduce standard templates
* Paving the way by communicating
* Planning an XML pilot

Change management
* Linking people and processes toward a desired change
* change is not where you are now
* need to know where you are going and tell those who you want to come with you
* "you are almost certainly under-communicating by a factor of at least 10 and possibly 100"

Carrying people with you. People view change as an attack on their current competence. Need to begin by celebrating what they have been doing right. 5-25% of people can't or won't be able to work with the new processes (Emma Hamer)

The change equation:

C = (ABD) > X

C = change
A = dissatisfaction with status quo
B = desirability of the new end state
D = risk and disruption to get there
X = cost of changing (effort, discomfort, difficulty, risk)

Carrying people with you
* celebration with is working
* explain what isn't and why
* describe how it will be with the new methods
* what's in it for them
* what's in it for the company
* what's in it for the clients

WIIFM = What's in it for me

* Active supporters
* Active dissenters
* Passive supporters
* Passive dissenters

Creating a change team
* You can't do all this by yourself.
* Special skills, talents, and leadership
* Where you can't carry, you may have to push or reallocate

First, Break All the Rules
Marcus Buckingham

Leadership is different from management. (That is SO true.)

Team members
* Champion or sponsor
* sustaining sponsor
* implementer
* change agent
* advocate

* group
* different styles, methods, and needs
* different personality types
* similar team gets quick results
* team with differences gets better result

Where change management goes wrong
* too much complacency
* lack of power in the guiding team
* not having real vision
* under-communicating (effectively)
* allowing obstacles to block the vision
* no short-term wins
* declaring victory too soon
* not embedding changes in practice

learning cycle
* concrete experience for activists
* reflective observation for reflectors
* theoretical concepts for theorist
* practical experimentation for pragmatists
(Experiential Learning, Kolb)

change
* needs leadership and vision
* needs good management
* needs metrics
* because ultimately it's about money
* increase revenue
* decrease costs
* make people's lives easier
* concentrate on the outcomes
* leave individuals to develop their own implementation plans

business process re-engineering
Customer led analysis method for business re-engineering
1. establish the scope
2. target the customer
3. model the process
4. analyze the structure
5. create the opportunity
6. redesign the process
7. refine the customer experience
8. ??

Why?
* customers dissatisfied
* position in value chain changes
* move from product to service or vice versa
* merger with another organization
* has to be customer-led
* good business case
* beware of targets (wrong targets lead to undesired behavior)

Influencing others
* getting results with authority
* you can't change other people
* you can change what you do, which may change how others react to you
* need to be politically savvy

Effective influence
* open
* honesty
* integrity
* loyalty
* rapport

* adult to adult communication and relationships
* maximal listening
* dovetailing needs outcomes

Strategies
* Logic
* Personal appeal
* Networking
* Bargaining
* Assertiveness
* Hierarchical appeal

Great presentation, and happy to see that my anecdotal experience has some amount of overlap with Ant's much more research-backed approach.

Labels: , ,


6:51 AM Permalink | |

divider

 

STC UK: Almost live, part one...Lessons on Introducing XML Publishing

Sunday, June 22, 2008 — posted by Sarah

[updated to correct number of employees]

I attended STC UK's Trends in Technical Communication this weekend. For once, I actually got to be a regular participant in the sessions. And I got to vote on chapter-related matters (as I joined it this year).

Shannon Milsom of Cambridge Silicon Radio delivered an excellent overview of their XML implementation and lessons learned.

When she joined the company eight years ago, she was employee number 69; CSR now employees 4,000 people and 1,000 in the UK1,000 people. They create chips for Bluetooth (market leader), wireless, GPS, and other radio technologies. Most of their customer base is in Asia.

Development is in the UK and UK; "fabless" manufacturing in East Asia. Sales everywhere.

Their original workflow used Word and had all the usual problems you might expect. Styles were corrupt and style guides were not followed. As the company grew, the problems became worse. Single sourcing was needed for shared content; the copy and paste approach led to a risk of missing changes. Content from SMEs needed heavy editing and fixes of bad Word usage -- they created their own individual styles and made a huge mess -- and that assumes that they actually used the official template.

They had a wide range of content, and they classified it by product status (which is interesting and I don't think I've ever seen before):
Side note: A slide with the various contributors and roles includes an excellent graphic of the software guy as a hippie California dude with a tie-dyed shirt. Sales and marketing on the beach under the umbrella with a laptop.

Their goal was to have:
In addition to The Usual, their reasons for moving to XML include the ability to substitute "common text," such as the product name and number, document type, and document status.

Modular authoring results in a workflow where they build documents from common blocks. If a block has been "released" (I think this means reviewed and approved), it can be used as needed.

Benefits they see from XML:
They considered building their own CMS but eventually bought. After a few trials and a false start with a product that didn't work, they ended up with Ovidius TCToolbox, which they are very happy with.

Lessons learned
Issues to consider
Focus on:
Involve...
Today's language lesson: "trial" as a verb, as in "We trialled XYZ, but didn't like it."

Labels: , ,


4:52 PM Permalink | |

divider

 

STC 2008: Wrap-up

Thursday, June 05, 2008 — posted by Sarah

The STC conference in Philadelphia just flew by. I think I managed to attend only two sessions other than the ones where I was participating.

Many thanks to those of you who stopped by the booth to meet us. We especially appreciate visitors who tell us that they read and enjoy our content, whether books, white papers, or this blog.

I had numerous requests for my paradigm shift presentation slides, so I am making them available here:


SlideShare | View | Upload your own



My next round of conferences will be in the UK. I'm leading an XSL workshop for STC UK on June 22 and giving a presentation on June 21 as part of the Trends in Technical Communication event. Then, it's onward to X-Pubs, where I'll be discussing the implications of Web 2.0 on technical communication.

As far as I know, after that I'm done with the conference circuit until the fall. However, senior technical consultant Simon Bate will be attending the Gilbane conference in San Francisco and participating on a DITA panel. Please contact us if you'd like to set up a meeting at the conference.

Labels: , , ,


1:44 PM Permalink | |

divider

 

WritersUA: DITA pilot techniques

Wednesday, March 19, 2008 — posted by Sarah

Mark Wallis of IBM ISS on how to run a successful DITA pilot. Some great information in this presentation on how to reduce risks.

He recommends selecting your pilot project based on the following items:
They had one person out of a group of twelve, a "senior in name only" writer, leave because of this transition.

The ideal team for a pilot will need cross-functional and complementary skills:
Some advice on planning your content. (And it's worth noting here that these apply to good writing and topic-oriented content rather than to DITA tools.)
Some interesting discussion of "task support clusters," which include conceptual overviews, related tasks, deep concept, and reference information. (Michael Hughes did a presentation on this earlier today, which I unfortunately was not able to attend.)

They set up a DITA War Room in a small conference room and met at least daily (1.5 to 2 hours per day. Yikes). They set weekly goals and used small tasks to build momentum.

There was also heavy use of an internal wiki to put up initial "straw man" design, then revise, comment, and discuss.

Layering deliverables
Implementation deliverables were split out into smaller tasks, such as:
For the third time, he points out that they are no longer documenting how to use a check box, so I guess I'll mention it.

Choosing the DITA toolset

Task Modeler (free) for building and managing ditamaps, defining relationships between topics, and creating skeleton topics (stub files).

DITA-compliant editor to edit your topics.

Compiler (part of open source toolkit). Compiler? What are they compiling? HTML Help? Oh. He just referred to Ant as a compiler. Ohhhhhkay.

Proof of concept

They picked a subset of the pilot to do the proof of concept.

The presenter's boss is quoted as saying, "There's no such thing as bad weather, only insufficient clothing." I'm guessing that she's never been to Minnesota in winter.

The objectives for the proof of concept:
They learned that deliverable formats matter because they must deliver several different formats.

Managing costs

Purchase toolsets only for pilot team.

After completing proof of concept (successfully!), invest in tools for the remaining writers.

Wiki

They used their wiki to capture conventions and guidelines.

Improving acceptance

They paid attention to the change management issues. He doesn't mention it here, but I would assume that the combination of an acquisition by IBM plus the requirement to change the authoring environment could have caused significant angst. Their approach included presentations, wiki content, email discussions, and online training.

At the point of transition, DITA boot camp was offered.

They used collaborative walkthroughs, or reviews, to help standardize their content development. Interesting. This sounds as though it could be a) threatening and b) an unbelievable time sink. But just maybe it might also c) help improve the content.

Other lessons learned

Think more, write less. (Don't document the obvious, don't document common user interface convention, write only if you're really adding value.)

Don't squander your ignorance. (If something makes you stumble in the interface, that will probably also cause problems for your users, so capture it.)

The more structured your content, the easier the transition to DITA.

Documenting the obvious teaches readers to ignore your text, so don't document the obvious.

The handouts are available here: http://www.writersua.com/ohc/suppmatl/

Labels: , , ,


5:29 PM Permalink | |

divider

 

Culture clash

Tuesday, February 19, 2008 — posted by Sarah

[Disclosure: I have several friends who work at IBM and Scriptorium is an IBM vendor.]

Both IBM and Tata Consultancy Services have recently laid off employees in India.

I think it's fair to say that many Indians are shocked by this development. At least one person says that the interviewers should be let go because they did a bad job of evaluating people. Others are wringing their hands over ruined careers because the layoff means a black mark on your resume.

And, with much sympathy, I say to them, "Welcome to our world." Layoffs are a fact of life in the U.S. I started Scriptorium after a layoff and I think that most people in high-tech have a layoff (or two or three) in their job history.

For U.S. workers in the generation that is now retired, getting laid off was in fact shameful. I remember one colleague back in 1996 who told his father about his layoff. His father, who worked his entire career at one large corporation, said to him, "What did you do wrong?" (thanks, Dad) But today, layoffs happen. Corporations merge, or don't meet their revenue targets, or overextend themselves, and then they lay people off.

The multinationals, like IBM, have brought this mentality to India. But Indian expectations appear to be that, once hired, you get to stay.

In BusinessWeek, we find a flattering story about Tata's approach to acquisitions:
Tata's unique shareholder structure makes it easier for the group to tread lightly. Since its founding in 1868, Tata has been controlled by charitable trusts. Today, they own 66% of parent Tata Sons' shares and aren't as focused on short-term gains as most investors. The trusts, says R.K. Krishna Kumar, a director with Tata Sons, have long insulated employees "from the greed that is sweeping the corporate world." As the company gets more deeply enmeshed in the global economy, that gentility will be put to the test. Says Harvard Business School professor Tarun Khanna: "There's a different kind of rough-and-tumble to competitive pressures outside of India."
And it looks as though this is already happening.

Employee costs in India to U.S. costs are rising quickly because of the exchange rate (weak dollar/strong rupee) and salary increases. As a result, the standards for Indian employees must rise as well. (If you cost more, you had better add more value.)

For U.S. employees, the Indian layoffs may be an oddly hopeful sign. Rick Smith says this at wral.com in an opinion post:
The evidence right now is anecdotal, but the IBM fresher story could mark a tipping point in offshoring/onshoring. Stay tuned.
At least life in this industry is never boring.

Various reactions:
pluggd.in
digitalbhoomi.in
Yahoo News India
humsurfer.com

Labels: ,


1:59 PM Permalink | |

divider

 

The Age of ... Expertise?

Wednesday, September 05, 2007 — posted by Sarah

Over on O'Reilly's Radar blog, Andy Oram has a fascinating article about the demise (!) of the Information Age and what will be next:
[T]he Information Age was surprisingly short. In an age of Wikipedia, powerful search engines, and forums loaded with insights from volunteers, information is truly becoming free (economically), and thus worth even less than agriculture or manufacturing. So what has replaced information as the source of value?

The answer is expertise. Because most activities offering a good return on investment require some rule-breaking--some challenge to assumptions, some paradigm shift--everyone looks for experts who can manipulate current practice nimbly and see beyond current practice. We are all seeking guides and mentors.

What comes after the information age? (be sure to read the comments, too)
It's an interesting idea, but I don't think we're getting away from the Information Age into the Expertise Age. After all, expertise is just a specialized (useful!) form of information.

In the comments, Tim O'Reilly points out that the real change is in how information is gathered and distributed with "the rise of new forms of computer mediated aggregators and new forms of collective curation and communication."

I believe that we are still firmly in the Information Age because information has not yet become a commodity product. There is, however, clearly a shift happening in how information is created and delivered. I think it's helpful to look at communication dimensions:
Technical support is the most expensive option; it's also often the most relevant. Technical writing is more efficient (because the answer to the question is provided just once), but also less personal and therefore less relevant.

Many technical writers are concerned about losing control over their content. For an example of the alarmist perspective, read Joanne Hackos's recent article on wikis. Then, be sure to read Anne Gentle's eponymous rebuttal on The Content Wrangler.

Keep in mind, though, that you can't stop people from creating wikis, mailing lists, third-party books, forums, or anything else. You cannot control what people say about your products, and it's possible that the "unauthorized" information will reach a bigger audience than the Official Documentation(tm). You can attempt to channel these energies into productive information, but our new information age is the Age of Uncontrolled Information.

Furthermore, the fact that people are turning to Google to find information says something deeply unflattering about product documentation, online help, and other user assistance. Why is a Google search more compelling than looking in the help?

Labels: ,


1:29 PM Permalink | |

divider

 

Facebook

Saturday, September 01, 2007 — posted by Sarah

In the past couple of weeks, I read an excellent post from Dave Kellogg about Facebook, and then received an invitation to join from a fellow technical writer.

So I did.

Here are a few initial impressions:
I really wonder how Facebook might fit into a corporate communications strategy. Are there ways in which the Facebook platform might be used for technical support? Or for user forums? I can easily envision "We Hate Product X" groups, but I'm having a little trouble seeing how a more traditional user group might fit into Facebook.

Labels: ,


10:09 AM Permalink | |

divider

 

Inside our XML workshop...

Wednesday, July 11, 2007 — posted by Sarah

Leanne Rollins of the Southwestern Ontario STC posted a summary of the workshop I did in March. It gives you an excellent flavor of what these workshops are Really Like.

I particularly enjoyed this bit:
The planning requirements and cost implementation alone were enough to scare the entire the room into reassessing their *actual* authoring and publishing needs.
I call that success.

Labels: ,


9:28 AM Permalink | |

divider

 

When you have a hammer...

— posted by Sarah

...everything looks like a nail.

We all suffer from this syndrome to a certain extent. Once you develop familiarity with a particular tool or technology, you see possibilities everywhere.

Sean McGrath refers to this as the Just Use X Club. He is none too happy with the rising membership in Just Use X and proposes a counter-organization:
A second club needs to be formed called "When not to Just Use X" club. This group should devote itself to taking all values of X from the "just use X" club and listing off all the scenarios in which each X should not be used. They should also list off all of the things which will not automatically be true by virtue of the use of X. They should also list off all the areas where good old fashioned thought and design and hard work cannot be replaced by the simple gambit of using X.
This fall's Intercom will launch my new column, tentatively titled The XML Strategist. The first installment is devoted to scenarios in which XML is not appropriate.

It would appear that Mr. McGrath and I are kindred spirits.

Labels: ,


8:42 AM Permalink | |

divider

 

Understanding change resistance

Wednesday, July 04, 2007 — posted by Sarah

Implementing new technology presents numerous challenges -- choosing new software, training staff on new technology and processes, setting up new workflows, and so on. For technical writers, the transition from traditional desktop publishing to XML-based workflows requires a significant shift in mindset. Instead of focusing on the appearance of the final deliverable (usually on paper), writers must now give up control over formatting, follow a set of structure rules, and assume that the end result will be formatted automatically.

You should not underestimate the difficulty that this transition presents. With that, I was disappointed to see the following at Accelerated Authoring:
If Pete decides to go for DITA, he’ll have to [...] persuade management, get a budget, train writers and figure out how to manage the transition. Not easy. And, if the transition is not smooth, Pete could be penalized.

On the other hand, Pete could get through the transition period to DITA and leverage the same team that he had yesterday to produce more documents, more focused documents, better documents. Is there risk in the transition? Of course, but that’s what life is about - adapt or disappear.
No.

"Pete" must first determine that the benefits of XML-based authoring outweigh the costs. Then, Pete needs to think about whether DITA is the right choice for his organization's content.

DITA is not right for everyone. XML is not right for everyone.

Keep in mind that the benefits of XML generally go to management and the difficulties (worse tools, less control, more constrained authoring) are imposed on authors.

If you're interested in more details, the slides from my Coping with the XML Paradigm Shift presentation are available here (PDF).

Labels: ,


11:24 AM Permalink | |

divider


Scriptorium Publishing | Post Office Box 12761 Research Triangle Park, NC 27709 | (919) 481 2701 | info@scriptorium.com