Skip to main content
Content strategy

The State of Structure

In early 2009, Scriptorium Publishing conducted a survey to measure how and why technical communicators are adopting structured authoring.

Of the 616 responses:

  • 29 percent of respondents indicated that they had already implemented structured authoring.
  • 16 percent indicated that they do not plan to implement structured authoring.
  • 14 percent were in the process of implementing structured authoring.
  • 20 percent were planning to do so.
  • 21 percent were considering it.

    • This report summarizes our findings on topics including the reasons for implementing structure, the adoption rate for DITA and other standards, and the selection of authoring tools.

    Download PDF file (2 MB, 56 pages)

    Discuss this document in our forum

ScriptoriumTech
December 31, 2009
Read More
News Opinion

Are you ready for mobile content?

A report from Morgan Stanley states that mobile Internet use will be twice that of desktop Internet and that the iPhone/smartphone “may prove to be the fastest ramping and most disruptive technology product / service launch the world has ever seen.” That “disruption” is already affecting the methods for distributing technical content.

With users having Internet access at their fingertips anywhere they go, Internet searches will continue to drive how people find product information. Desktop Internet use has greatly reshaped how technical communicators distribute information, and having twice as many people using mobile Internet will only push us toward more online delivery—and in formats (some yet to be developed, I’d guess) that are compatible with smaller smartphone screens.

The growing number of people with mobile Internet access underscores the importance of high Internet search rankings and a social media strategy for your information. If you haven’t already investigated optimizing your content for search engines and integrating social media as part of your development and distribution efforts, it’s probably wise to do that sooner rather than later. Also, have you looked at how your web site is displayed on a smartphone?

If you don’t consider the impact of the mobile Internet, your documentation may be relegated to the Island of Misfit Manuals, where change pages and manuals in three-ring binders spend their days yellowing away.

Alan Pringle
December 16, 2009
Read More
Opinion

Angst and authority

Clay Shirky has a fascinating post on the concept of algorithmic authority; the idea that large systems, such as Google PageRank or Wikipedia have authority (that is, credibility) because of the way that the system works. In other words, a page that is returned first in a Google search is assumed by the searcher to be more credible because it is ranked first.

That made me think about authority in technical content.

As an in-house technical writer, your words have authority and your content carries the corporate logo. But although this should theoretically increase your credibility, it seems that the reverse is true. Consider, for instance, the following hypothetical book titles:

  • XYZ User’s Guide—This document, produced by the makers of XYZ, is shipped in the product box (or downloaded as a PDF with the software)
  • XYZ Classroom in a Book—This document is available in bookstores and is produced by XYZ Press
  • XYZ: The Complete Reference*—This document is available in bookstores and is produced by a third-party publisher

Which of these books would you turn to for help? What are your expectations of each document?

I believe that credibility and thus authority increases with distance from the product’s maker. In other words, the third-party book has more authority than either of the other two. Credibility is compromised by close association with the organization that makes the product.

When we apply this concept to information on the web, the implications are troubling for professional content creators who work inside corporations. If corporate authorship decreases authority, we get this result:

online help < user forums on corporate site < user forums on third-party site

Will people looking for user assistance gravitate toward independent third-party sites? What does that mean for in-house authors? How can you increase your credibility as a corporate technical communicator?

* Feel free to substitute your favorite book series title: XYZ for Dummies, XYZ: The Missing Manual, The Complete Idiot’s Guide to XYZ, XYZ Annoyances, …. I should probably also mention that I have written both a Dummies book and a Complete Reference.

Sarah O'Keefe
December 15, 2009
Read More
DITA Webinar

2010: A DITA Odyssey

When you’re considering tools for authoring DITA content and creating output, there are many choices to evaluate. To make your journey toward DITA implementation easier, Scriptorium is offering free webinars in early 2010 to show you how three tools handle DITA-based information.

Odysseus in front of Scylla and Charybdis by Johann Heinrich Füssli (Wikipedia)

Odysseus in front of Scylla and Charybdis by Johann Heinrich Füssli (Wikipedia)

On January 19, Sarah O’Keefe will show you how MadCap Flare supports DITA constructs, and on February 16, Simon Bate will demonstrate the DITA features in the oXygen XML editor. On March 16, Scott Prentice of Leximation will demonstrate how the DITA-FMx plugin works with FrameMaker 9.

As an added bonus, attendees can win a free license of the tool shown during each demo! For more information about these sessions and to register, visit our events page.

If there are other topics you’d like to see covered in later free webcasts, please send suggestions to [email protected].

Alan Pringle
December 10, 2009
Read More
Webinar

Coping with webcast participation

Many thanks to all of the people who attended yesterday’s webcast on coping with user-generated content.

We recorded the webcast, and it is now available:

In a nod to the topic itself—and in an effort to make the event more interesting, I solicited quite a bit of audience participation. As a result, I owe the webcast participants a significant number of links and other resources.

Question: What blogs do you read?

Answer: Lots.

Better answer: Here is a link to my Google Reader subscriptions in the Publishing category. Many thanks to the attendee who recommended sharing them this way. (If you’d like full credit by name, send me email or put a note in the comments; I don’t want to do that without permission.) I’ve also listed the blogs at the bottom of this post.

In addition to the publishing blogs, I specifically mentioned Punk Rock HR, Dooce, and Mark Logic CEO blog. (Don’t read the first two if you are offended by a word that starts with F.)

Question: Are there any guides to legal issues in social media, such as libel?

Answer: I found a few interesting resources, but not a definitive guide.

Libel and Social Media (blog post)

IBM Social Computing Guidelines (these have been in the news as a template for a well-crafted policy)

Sarah O'Keefe
December 9, 2009
Read More
Tools

Adding a DOCTYPE declaration on XSL output

In a posting a few weeks ago I discussed how to ignore the DOCTYPE declaration when processing XML through XSL. What I left unaddressed was how to add the DOCTYPE declaration back to the files. Several people have told me they’re tired of waiting for the other shoe to drop, so here’s how to add a DOCTYPE declaration.

First off: the easy solution. If the documents you are transforming always use the same DOCTYPE, you can use the doctype-public and doctype-system attributes in the <xsl:output> directive. When you specify these attributes, XSL inserts the DOCTYPE automatically.

However, if the DOCTYPE varies from file to file, you’ll have to insert the DOCTYPE declaration from your XSL stylesheet. In DITA files (and in many other XML architectures), the DOCTYPE is directly related to the root element of the document being processed. This means you can detect the name of the root element and use standard XSL to insert a new DOCTYPE declaration.

Before you charge ahead and drop a DOCTYPE declaration into your files, understand that the DOCTYPE declaration is not valid XML. If you try to emit it literally, your XSL processor will complain. Instead, you’ll have to:

  • Use entities for the less-than (“<” – “&lt;”) and greater-than (“>” – “&gt;”) signs, and
  • Disable output escaping so that the entities are actually emitted as less-than or greater-than signs (output escaping will convert them back to entities, which is precisely what you don’t want).

There are at least two possible approaches for adding DOCTYPE to your documents: use an <xsl:choose> statement to select a DOCTYPE, or construct the DOCTYPE using the XSL concat() function.

To insert the DOCTYPE declaration with an <xsl:choose> statement, use the document’s root element to select which DOCTYPE declaration to insert. Note that the entities “&gt;” and “&lt;” aren’t HTML errors in this post, they are what you need to use. Also note that the DOCTYPE statement text in this template is left-aligned so that the output DOCTYPE declarations will be left aligned. Most parsers seem to tolerate whitespace before the DOCTYPE declaration, but I prefer to err on the side of caution:



 &lt;xsl:template match="/"&gt;

 &lt;xsl:choose&gt;

 &lt;xsl:when test="name(node()[1]) = 'topic'"&gt;

 &lt;xsl:text disable-output-escaping="yes"&gt;

&lt;!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"&gt;

&lt;/xsl:text&gt;

 &lt;/xsl:when&gt;

 &lt;xsl:when test="name(node()[1]) = 'concept'"&gt;

 &lt;xsl:text disable-output-escaping="yes"&gt;

&lt;!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"&gt;

&lt;/xsl:text&gt;

 &lt;/xsl:when&gt;

 &lt;xsl:when test="name(node()[1]) = 'task'"&gt;

 &lt;xsl:text disable-output-escaping="yes"&gt;

&lt;!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"&gt;

&lt;/xsl:text&gt;

 &lt;/xsl:when&gt;

 &lt;xsl:when test="name(node()[1]) = 'reference'"&gt;

 &lt;xsl:text disable-output-escaping="yes"&gt;

&lt;!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"&gt;

&lt;/xsl:text&gt;

 &lt;/xsl:when&gt;

 &lt;/xsl:choose&gt;

 &lt;xsl:apply-templates select="node()"/&gt;

 &lt;/xsl:template&gt;

The preceding example contains statements for the topic, concept, task, and reference topic types; if you use other topic types, you’ll need to add additional statements. Rather than write a statement for each DOCTYPE, a more general approach is to process the name of the root element and construct the DOCTYPE declaration using the XSL concat() function.



&lt;xsl:variable name="ALPHA_UC" select="'ABCDEFGHIJKLMNOPQRSTUVWXYZ'"/&gt;

 &lt;xsl:variable name="ALPHA_LC" select="'abcdefghijklmnopqrstuvwxyz'"/&gt;

 &lt;xsl:variable name="NEWLINE" select="'&amp;#x0A;'"/&gt;



 &lt;xsl:template match="/"&gt;

 &lt;xsl:call-template name="add-doctype"&gt;

 &lt;xsl:with-param name="root" select="name(node()[1])"/&gt;

 &lt;/xsl:call-template&gt;

 &lt;xsl:apply-templates select="node()"/&gt;

 &lt;/xsl:template&gt;



 <span style="color: green;">&lt;-- Create a doctype based on the root element --&gt;</span>

 &lt;xsl:template name="add-doctype"&gt;

 &lt;xsl:param name="root"/&gt;

 <span style="color: green;">&lt;-- Create an init-cap version of the root element name. --&gt;</span>

 &lt;xsl:variable name="initcap_root"&gt;

 &lt;xsl:value-of

 select="concat(translate(substring($root,1,1),$ALPHA_LC,$ALPHA_UC),

 translate(substring($root,2 ),$ALPHA_UC,$ALPHA_LC))"

 /&gt;

 &lt;/xsl:variable&gt;

 <span style="color: green;">&lt;-- Build the DOCTYPE by concatenating pieces.</span>

 <span style="color: green;">Note that XSL syntax requires you to use the &amp;quot; entities for</span>

 <span style="color: green;">quotation marks ("). --&gt;</span>



 &lt;xsl:variable name="doctype"

 select="concat('!DOCTYPE ',

 $root,

 ' PUBLIC &amp;quot;-//OASIS//DTD DITA ',

 $initcap_root,

 '//EN&amp;quot; &amp;quot;',

 $root,

 '.dtd&amp;quot;') "/&gt;

 &lt;xsl:value-of select="$NEWLINE"/&gt;

 <span style="color: green;">&lt;-- Output the DOCTYPE surrounded by &lt; and &gt;. --&gt;</span>

&lt;xsl:text disable-output-escaping="yes"&gt;&lt;

&lt;xsl:value-of select="$doctype"/&gt;

&lt;xsl:text disable-output-escaping="yes"&gt;&gt;

 &lt;xsl:value-of select="$NEWLINE"/&gt;

 &lt;/xsl:template&gt;

The one caveat about this approach is that it depends on a consistent portion of the public ID form (“-//OASIS//DTD DITA “). If there are differences in the public ID for your various DOCTYPE declarations, those differences may complicate the template.

So there you have it: DOCTYPEs in a flash. Just remember to use disable-output-escaping=”yes” and use entities where appropriate and you’ll be fine.

Simon Bate
December 1, 2009
Read More
Opinion

To bid or not to bid—a vendor’s guide to RFPs

Request for Proposal (RFP) documents usually arrive in the dead of night, addressed to sales@scriptorium or sometimes info@scriptorium.

Dear Vendor,

LargeCompany is looking for a partner who can work magic and walk on water. Please refer to the attached RFP.

Signed,

Somebody in Purchasing

Our instinct is to crack open the RFP and start writing a proposal. But over time, we’ve learned to take a step back and evaluate the RFP first to ensure that it’s worth our time.

In this post, I’ve outlined some of the issues that we consider before responding to an RFP.

Qualifications

Are we qualified to do the work that the RFP is asking for? More importantly, are we qualified in the customer’s eyes? Many RFPs delineate evaluation criteria, which may not be relevant (in our opinion) to the task at hand. For example, we once saw a proposal for an Interleaf to FrameMaker conversion project that demanded expert knowledge of Interleaf. I would think that expert knowledge of FrameMaker would be more important, but the customer wanted Interleaf knowledge. FrameMaker was mentioned in passing. We decided in that case that our expert knowledge of the Interleaf-to-FrameMaker conversion process(es) should compensate for our minimal Interleaf expertise.

But if the RFP demands expertise that we simply do not have, and if that expertise, however irrelevant, will be weighted heavily in the evaluation, investing in a proposal is risky. The fact that we know we can do the project well is irrelevant if that customer will discard our proposal for lacking a required element.

Some days you’re the windshield, some days you’re the bug

It’s critically important to figure out whether an RFP is really looking for a vendor or not. Especially in large organizations and for larger projects, multiple bids are often required. The customer may already know exactly who they want to work with, but their purchasing department requires a minimum number of bids (usually three). Thus, the customer writes an RFP to get “column fodder”—the sacrificial second and third proposals to go along with the vendor that they really want.

We have experience on both sides of this issue. Sometimes, we’re the preferred vendor; sometimes, we’re the one getting the unwinnable RFP. Identifying cases where we have no chance of getting the business is critical to avoid wasting our time. Unfortunately, it’s also a bit of a black art. But here are some factors to consider:

  • Did the RFP parachute in from nowhere, or have we had previous contact with the organization?
  • Are there unusual requirements in the RFP? (For example, we decided against responding to an RFP that stated that close proximity to the customer would be a significant weighting factor. Not-so-coincidentally, one of our competitors just happened to have an office nearby.)
  • Is the project a marginal fit for our services? (In an effort to find additional vendors, the purchasing department might do a quick Google search and then broadcast the RFP. For instance, we get quite a few RFPs requesting outsourced technical writing services. Not the best fit for us.)
  • Is the customer unwilling to have a conference call to discuss questions we have about the RFP?

Most importantly, if your intuition tells you that there’s a problem, pay attention.

Funding

First and most importantly, is the project funded? In one painful case, we wrote a proposal and made the trek to the customer’s office (which was, naturally, on the other end of the country) to present our solution. (This site visit was explicitly required under the terms of the RFP.) Six weeks later, we found out that the evaluation committee had presented their recommendation to upper management and had been denied funding. In other words, the people who issued the RFP did not have approval for the project.

Assuming that funding is in place, there is the question of whether the funding will be sufficient. If the customer thinks their problem can be solved for $20,000 and our proposal totals $100,000, the sticker shock alone will probably be enough to kill our chances. This is why we often ask prospects about their expectations: how long do they think the project will take? How many people do they think should be assigned to the project? In some cases, we ask directly what the budget is.

How are bids evaluated?

RFPs that demand a list of services and hourly rates are a bad sign. Interestingly, government RFPs usually spell out evaluation criteria, using language such as this:

Selection of an offeror for contract award will be based on an evaluation of proposals against four factors. The factors in order of importance are: technical, past performance, cost/price and Small Disadvantaged Business (SDB) participation. Although technical factors are of paramount consideration in the award of the contract, past performance, cost/price and SDB participation are also important to the overall contract award decision. All evaluation factors other than cost or price, when combined, are significantly more important than cost or price. In any case, the Government reserves the right to make an award(s) to that offeror whose proposal provides the best overall value to the Government.

Corporate RFPs seem to avoid any mention of evaluation criteria, other than to state that certain items are required in a proposal or the proposal will be deemed “non-responsive.” The dreaded “non-responsive” label is attached to a proposal that does not meet the requirements of the RFP. For instance, if the RFP indicates that a response must include resumes and resumes are not included, the entire proposal could be discarded as non-responsive.

Evaluating risk

The decision whether or not to bid on an RFP comes down to evaluating the risk. Factors include:

  • Do we have other RFPs that look more appealing?
  • Are the deadlines reasonable (both for the proposal and for the project described therein)?
  • How many others will respond to the proposal?
  • How well does the customer understand the issues?
  • Does the RFP demonstrate an understanding of the problem the customer is trying to solve?
  • Has the customer already decided on their preferred solution and do we agree with the approach they want to use?
  • Are the evaluation criteria clear and relevant?
  • What is the pricing structure?
  • Does the project look interesting to us?
  • Do we want to work with this customer?

Of course, even with all these factors, the decision often hinges on intuition. Perhaps there’s something not quite right about the RFP. Turning away work (or potential work) is always difficult, but I think we’re getting better at sniffing out RFPs where we truly stand no chance of success. Or perhaps, despite several risk factors, we believe that we can work well with the customer and make a useful contribution.

Sarah O'Keefe
November 30, 2009
Read More
Opinion

Would you use just a gardening trowel to plant a tree?

As technical communicators, our ultimate goal is to create accessible content that helps users solve problems. Focusing on developing quality content is the priority, but you can take that viewpoint to an extreme by saying that content-creation tools are just a convenience for technical writers:

The tools we use in our wacky profession are a convenience for us, as are the techniques we use. Users don’t care if we use FrameMaker, AuthorIt, Flare, Word, AsciiDoc, OpenOffice.org Writer, DITA or DocBook to create the content. They don’t give a hoot if the content is single sourced or topic based.

Sure, end users probably don’t know or care about the tools used to develop content. However, users do have eagle eyes for spotting inconsistencies in content, and they will call you out for conflicting information in a heartbeat (or worse, just abandon the official user docs altogether for being “unreliable”). If your department has implemented reuse and single-sourcing techniques that eliminate those inconsistencies, your end users are going to have a lot more faith in the validity of the content you provide.

Also, a structured authoring process that removes the burden of formatting content from the authoring process gives tech writers more time to focus on providing quality content to the end user. Yep, the end user doesn’t give a fig that the PDF or HTML file they are reading was generated from DITA-based content, but because the tech writers creating that content focused on just writing instead of writing, formatting, and converting the content, the information is probably better written and more useful.

Dogwood // flickr: hlkljgk

Dogwood // flickr: hlkljgk

All this talk about tools makes me think about the implements I use for gardening. A few years ago, I planted a young dogwood tree in my back yard. I could have used a small gardening trowel to dig the hole, but instead, I chose a standard-size shovel. Even though the tree had no opinion on the tool I used (at least I don’t think it did!), it certainly benefited from my tool selection. Because I was able to dig the hole and plant the tree in a shorter amount of time, the tree was able to develop a new root system in its new home more quickly. Today, that tree is flourishing and is about four feet taller than it was when I planted it.

The same applies to technical content. If a tool or process improves the consistency of content, gives authors more time to focus on the content, and shortens the time it takes to distribute that content, then the choice and application of a tool are much more than mere “conveniences.”

Alan Pringle
November 25, 2009
Read More
Webinar

The revolution will not be authorized

In the past few days, STC has been sending out acceptance notices for presentations at next May’s STC Summit. There’s been a small flurry of announcements, mostly on Twitter. (I live in North Carolina where two flakes are a flurry. 10 flakes are a school-closing, bread-and-milk-buying emergency.)

For instance, we have this on Friday, November 20:

Tweets related to STC acceptances

Tweets related to STC acceptances

Side note: I’ll be presenting on managing in an XML environment.

In the pre-Twitter Era, acceptances were sent by mail, and then conference organizers could post the full program more or less at their convenience. But now, the leaks start almost immediately.

This may not be a bad thing. The happy tweets raise awareness of the event. For an organizer, however, it means that notifications need to be carefully synchronized or perhaps staggered on a formal schedule (SxSW does this quite well; they announce program decisions in batches).

It seems like another case where unofficial community content is eroding the ability of the content owner to control the messaging. Coincidentally (!), that’s the topic of a webcast I’m doing on December 8.

Strategies for coping with user-generated content
Tuesday, December 8, 11 a.m. Eastern time

We are offering this webcast for free; you just need to register.

This is a new presentation that I first delivered at LavaCon in New Orleans this year.

Sarah O'Keefe
November 23, 2009
Read More
Opinion

Fear the peer

(This post is late. In my defense, I had the flu and the glow of the computer monitor was painful. Also, neurons were having trouble firing across the congestion in my head. At least, that’s my medical explanation for it. PS I don’t recommend the flu. Avoid if possible.)

Which of these scenarios do you think is most intimidating?

  1. Giving a presentation to a dozen executives at a prospective client, which will decide whether we get a project or not
  2. Giving a presentation to 50 people, including half a dozen supportive fellow consultants
  3. Giving a presentation to 400 people at a major conference

I’ve faced all three of these, and while each scenario presents its own set of stressors, the most intimidating, by far, is option #2.

In general, I’m fairly confident in my ability to get up in front of a group of people and deliver some useful information in a reasonably interesting fashion. But there is something uniquely terrifying about presenting in front of your peers.

Torches // Flickr: dantaylor

At LavaCon, I faced the nightmare—a murderers’ row of consultants in the back of the room, fondling various tweeting implements.

Here are some of the worst-case scenarios:

  • No new information. I have nothing to say that my colleagues haven’t heard before, and they could have said it better.
  • Disagreement. My peers think that my point of view is incorrect or, worse, my facts are wrong.
  • Boring. I have nothing new to say, my information is wrong, and I’m not interesting.

Of course, my peers were gracious, participated in the session in a constructive way, and said nice things afterwards. I didn’t even see any cheeky tweets. (I’m looking at you, @scottabel.)

All in all, I’d have to say that it’s a lot more fun to sit in the back of someone else’s presentation, though. Neil Perlin handled his peanut gallery deftly, asking questions like, “With the exception of the back row, how many of you enjoy writing XSLT code?”

Rahel Bailie said it best, I think. After completing her excellent presentation, she noted that presenting in front of peers is terribly stressful because, “I really want you to like it.”

Sarah O'Keefe
November 11, 2009
Read More