Random thoughts about publishing
Site Feed
Palimpsest
Thursday, June 26, 2008
Web 2.0 and Truth
My presentation at X-Pubs was about the impact of Web 2.0 or user-generated content on technical communication. (You can view the presentation at the bottom of this post.)
A phrase I heard repeatedly in reference to professional content was "a single version of the truth," which alludes to the idea that you should only have one instance of any given piece of content.
And that got me thinking. There are many areas of tech comm where this idea makes sense.
User-generated content, though, is in direct conflict with a single, unchanging, objective truth. Wikis, by definition, have content that is constantly evolving.
Furthermore, there's truth and then there's, well, truth. Compare and contrast these two snippets:
"The ABC feature is unusable. Use the XYZ as a work-around."
"You can use ABC to do blah blah. Here's how:(many annoying steps)"
Which one is truth? Both? More importantly, which one is more useful to the reader?
It takes a brave or maybe foolish corporate technical writer to criticize their own product explicitly. (This, in turn, is probably why third-party computer trade books sell so well. Somehow, I don't see a title like Word Annoyances getting the Microsoft seal of approval.)
But even though technical writers try to act as user advocates, there's a built-in conflict of interest -- technical writers are paid by corporations, not by users.
User-generated content meets a need that corporate technical publications do not (or perhaps cannot). It provides unfiltered, opinionated, and user-biased coverage of technical topics.
Why is there a gap between professionally created technical publications and the end users?
1. Updates can take a long time to get into the official documentation because of lengthy review, approval, and publishing processes.
2. Annotation capabilities are rarely provided to users. If they are, they're usually fairly limited.
3. The documentation is not sufficiently candid.
What are the implications for technical writers?
1. Document publishing needs to accelerate.
2. Online documents should allow for comments and discussion.
3. The documentation needs to be explicit about product limitations and workarounds.
In effect, technical writers need to have more of an editorial voice.
Here is my Web 2.0 presentation:
Notes: Use the arrow keys to navigate through the slides. The first slide may take a few seconds to come up; the presentation file is quite large.
Labels: analysis, conferences, web 2.0, xpubs
11:21 AM Permalink | |
Wednesday, June 25, 2008
No more DRaMa: DRM-free books
O'Reilly has announced it will start selling some titles as ebook bundles free of digital rights management (DRM) in July. I'm sure a lot discussion went into that decision because we have grappled with this very issue for our Scriptorium Press titles.
When we decided to release our FrameMaker workbooks in PDF format in February 2006, we opted not to use DRM restrictions that prevent printing or that lock the file to a particular computer. It was not an easy decision to make. We don't want our materials to be pirated, but at the same time, we don't want to implement DRM that can make life difficult for legitimate users. (What if you get a new laptop and your PDF file is locked down to your old one?) We also did a survey a few months ago on digital books, and folks made it very clear they would avoid files with DRM.
With the recent release of our Publishing Fundamentals: Unstructured FrameMaker 8, we took our sales of digital books even further. For the first time, we are offering buyers the option of purchasing a new reference book as a PDF file; previously, we offered digital versions for older reference books that we no longer printed. Another change with this latest release is that buyers who get the printed version also get the PDF version free. As is the case with our other digital versions, the PDF file of Publishing Fundamentals: Unstructured FrameMaker 8 is free of the DRM restrictions I mentioned earlier.
Releasing our content without any DRM may seem foolish to some. ("You're too trusting!" "You're inviting people to steal your stuff!") That being said, DRM can be a huge hassle for people who actually paid for the material, and it also can be cracked. Those are two big reasons we have opted not to use it.
10:35 AM Permalink | |
English lessons
I'm at London's Heathrow airport, getting ready to return home. Many thanks to the organizers of the STC UK and X-Pubs events for wonderful hospitality (special thanks to Ant Davey who picked me up at the airport when I arrived at 6:30 in the morning).
Some observations about my week in the UK:
- During conference sessions, you can expect that participants will not ask any questions until the end of the session.
- Questions are often quite pointed, far more so than in the U.S. I've noticed this on the BBC news as well. The question is phrased politely, but the general paraphrase is something like, "Well, that's all very nice, but isn't it true that blah completely undermines what you are saying?" For instance, you might get a question like, "You're really pushing for XML here, but isn't it true that XML isn't actually applicable for many situations?" Um. (Incidentally, participants in Germany frequently challenge the presenter as well. Not that there's anything wrong with that...)
- There is no such thing as a "British" accent. I heard an unbelievably variety of different accents and inflections, including Irish, Northern Irish, Scottish, northern England, southern England. The natives here can place accents with remarkable accuracy. And let's not forget variations from the non-native speakers, such as Germans and eastern European. It's quite fascinating, and for me, at least, some accents are much harder to understand than others. In particular, I found that long sentences were much easier to understand than a quick question. As a result, I was constantly asking service personnel to repeat themselves (they tend to ask short questions like, "checking in?").
- The X-Pubs attendees were mostly men, not too surprising with the emphasis on the defense (defence) industry and aerospace. But quite a different demographic from STC.
- There's been recent discussion about the relative lack of blogging or twittering at STC, but at these events, there was none (except for me). With wireless access clocking in at around $30 per day, it's not that surprising.
- The current exchange rate is really, really, really painful.
Labels: conferences, presentations, stc2008, xpubs
4:26 AM Permalink | |
Tuesday, June 24, 2008
Building communities one IP address at a time
Day 2 at Gilbane: Continuing in the Social Computing track
Case studies in collaborative computing
- Frank D'Angese - EarthKnowledge.net
- Mark Yolton - SAP Communities
- Kym Harrington - Sales Edge
- Work best when they are orchestrated, rather than moderated.
- Rating and ranking of contributers increases quality of the contributions.
- SAP encourages quality by having users award 3, 6, or sometimes 12 points to contributers. When they reach 250 points, they're considered "top contributors" or "highly-active contributors."
- The super-top contributors (1/100th of 1% of the best in points, professionalism, and maturity in collaboration) are identified as SAP Mentors.
- Management can be concerned in adopting web 2.0 because of exposing weaknesses to competitors, general risk, and disruptive technologies.
- SAP sponsors occasional get-togethers so that contributers can meet each other.
Some risks of sponsoring a user community:
- Self-promoters and anti-social behavior. Both of these are often handled by the community. "Public humiliation is more effective than policing." sez SAP.
- If your company participates, beware of inauthentic interaction.
- Sometimes users will vent about the product or company.
- A "dead" community (no one goes there) will project a bad image.
Heard in several places. Support calls can be grouped into two classes: How-to questions and true bugs. The point of a user community is to reduce (or entirely offload) support time spent on how-to questions.
User communities follow the "1-9-90" rule. That is 1% of the community are highly active participants, 9% are occasional contributers, and 90% are consumers of the information. SAP focuses on the 9% and encourages them to move into the top 1%.
English tends to be the "lingua franca" of user communities. Multilingual sites present a challenge, because they can be difficult to moderate.
While some communities offer live chat, it doesn't have the value of public forums, because the information in a forum is captured permanently. Live chat is not as public and much harder to track and follow.
Social Media at Tipping Point
- Geoffrey Bock - Gilbane Group
- Rachel Happe - IDC
HP Wetpaint -- Advice was so good, people in printing got annoyed.
Worth visiting.
Use of LinkedIn varies by industry. The overall average is 14%. For low-tech companies, use is as low as 2%; high-tech it's closer to 40%.
24% of all employees use some form of social networking.
Only 2% microblog (but I think that reflects much more on the novelty of the concept, rather than an acceptance level).
Gulp. 19% of the US workforce will retire in the next 5 years (this data is a couple of years old). There's a lot of knowledge that will leave along with the people. How do we capture all the knowledge? The preceding figures show that not everyone will use social computing or communities to record what they do. One approach is to establish (and record) conversations with these people.
On the other hand, 41% of 18-35 year-olds use social media and expect it at work. Social media gives them more access to tools, people, etc. It's NOT for just fun, they know it works faster.
Total content of the internet:
161 Exabytes (Millions of Terabytes) in 2006
900+ Exabytes by 2010
It's expected that at that time 80% will be user-created.
Technology for Ad Hoc Information Sharing (open source)
- Peter Monks - Alfresco (filling in for John Newton)
- Dries Buytaert - Drupal
- Michael Wechner Wyona.com
The enterprise sofware sales model is obsolete.
Open source eats $60B a year from traditional enterprise software. Open source is characterized as the "Ultimate Disruptive Technology".
No cost of sales
Typically 7/10 of sales costs fund sales cycle
In Open Source 7/10 plowed into R&D.
MSFT thinks SharePoint will be next platform beyond Windows.
Humans are social animals. The don't want processes. Need minitools to figure out what to do -- particularly for non-tech doc. Technology gets in the way.
Check out Forbes Office Pranks (http://officepranks.forbes.com/).
Terms to pay attention to
- Taxonomies - important to content management; critical to searching.
- JSR-283 - An upcoming Java API for content retrieval.
- RDF - Resource Descriptor Framework, a language for representing metadata. I considered (and passed on) using RDF in one of our projects, mostly because of what seemed like massive overhead. It's probably worth a second, or third, look.
Toolsmith's observations
There is no microblogging tool for the Enterprise (yet).Many of the tools that make up Web 2.0 have been available for a while. What is different is that a) there is a critical mass of "next generation" tools and b) these tools have been embraced by web communities and the enterprise.
These include:
- Developer communities
- Groups/ forums
- Blogs
- Wikis
- Ajax
Labels: conferences, gilbane08
4:12 PM Permalink | |
XPubs: Information integration and the needs of the (product) maintainer
Chris Wood
BAE Systems
Tech pubs managers at BAE, contributor to S1000D standard.
Electronic maintenance (interactive electronic technical manual, or IETM) has been shown to deliver increase in fault finding success, reduction in troubleshooting time, and reduction in maintenance errors. "Fairly comforting"
Market drivers for integrated information...output-based contracts. The Royal Air Force is asking vendors to take on more maintenance activities. The drivers for success for the commercial organization are different from the drivers for the military.
BAE must guarantee that a specific number of aircraft ("platforms") are available to fly at all times. Financial penalties for not meeting those goals.
Offshore commodity outsourcing is putting pressure on the prices that BAE can quote. Price "per page" needs to be on a downward slope.
IETM capability offers an opportunity to integrate support information applications and processes.
ATTAC Contract = a certain number of Tornado aircraft must be available 24x7. BAE is responsible for preflight, postflight, AND other maintenance. Spare parts come out of BAE's budget. Therefore, reducing spare parts "footprint" saves money.
18 million pounds (double that for dollars) over 10 years. Their target is to save more than 18M pounds by including rich data (photos, video, 3D animation), align with actual maintenance activities, tech pubs people on-base as part of integrated engineering team.
Nice example of specific changes in tech docs leading to large cost savings due to fewer returns for repair.
Aha. They improved the official documentation by picking up information that was "plastered on the wall" in the aircraft hangar. In other words, user-generated content!
Information integration...the issue
Too much information, which is necessary and can be integrated, but...who generates it? where? who approves it? who can receive it? is there a recognized authority?
What about information generated by maintenance personnel for use by engineers (the stuff on the wall)? Is there an approval route? How authoritative is it?
In the past, the separation between maintenance and design authority was clear. As the maintenance and design operation moved closer (or become the same in BAE's case), the needed separation of content becomes much more challenging. Does linking from engineering authority content to non-engineering authority corrupt the authoritative content?
What level of authority does information have? Has it been tested? Have is gone through an approval route?
Approved data architecture. The challenge is to define a data architecture that includes all information issues by the design authority for the purpose of operating and/or mainteaining the platform in services, ensuring it is efficient, effective, and safe.
"This is a major content management issue." Indeed.
Many information deliverables go through rigorous approval process, but maintainers have access to other information, too. Official deliverables must be more integrated. Reference data and maintenance procedures come from different places in the organization, but they need to be in alignment. And there are "modifications," which must go in both places.
"This is not a trivial challenge." Yep.
The conflict here is really between data (approved content) and lore (unofficial information about how things really work). The mechanics have the "lore," and need to be persuaded to share it to improve the official documentation over time.
Labels: conferences, xml, xpubs
8:43 AM Permalink | |
Monday, June 23, 2008
Garlic Delight
Today, a few traveling coworkers missed out on Georgina's fragrant garlic rolls. Simon and Sarah, here's a photo for your viewing pleasure:
On our last visit, a few of us were a bit cranky when our waitress didn't serve the rolls. And in the lunch rush, we had no time to demand the greasy little delights. This time, thank you very much, the basket was delivered shortly after we ordered.It's the little things...
Labels: cranky, garlic, georgina's
5:41 PM Permalink | |
XPubs: DITA implementation in progress
Chris Hadley of Micro Focus
Noz Urbin of Mekon
Micro Focus
12 writers in four locations
rapidly growing team, but also 20-year company veterans
Content is in XML, written using XMetaL, stored in CVS, DTDs and XSLT developed in-house.
Acquired companies have content in FrameMaker and Word.
Delivery in CHM, HTML, Help 2.
Lots of reuse in places; none in others.
No localization.
Problem very interesting because second generation of XML implementations are beginning. System was developed in-house, which was cutting edge at the time but now showing its age. It is costly to maintain, and the experts have left. Company cannot manage, debug, or improve the processes that exist.
Cannot continue to rely on in-house solutions because of risks of breakdowns. Change was required.
Business case 1: Value to customer
Improve quality of content with reuse, consistency, and accuracy.
Improve search. ("Content is great...when I can find it.")
Publishing to different formats.
Business case 2: Value to business
More accurate documentation with information easier to find means lower support cost due to fewer calls.
Lower cost on development. If support can find answers in documentation, there's no need to ask development team. Development team also uses documentation.
Reducing time on non-writing tasks such as builds means more time available for writing content.
Business case 3: Value to doc team
Replace aging systems and processes before they affect ability to deliver
Sustainable and manageable systems that can work even if there is employee turnover.
Align with industry standards (key reason). Open source expertise is transferable from other organizations, helps with recruitment.
Project started at the end of 2007. They engaged Mekon to help with the analysis of the current situation. By February 2008, they chose a CMS (TriSoft). Engaged Mekon to convert content to DITA. Installed and configured TriSoft. Primary consideration was cost, and they were required to give a budget figure to their board before they knew what they were going to be doing.
Why a CMS? They needed software that was supported externally instead of being produced in-house. Secondary priorities were reuse ("a single version of the truth") and publishing issues (multiple formats and audience, building and testing, link management).
Why DITA? Decision to DITA was very difficult. But the same arguments that applied to externally supported software applied to the DITA issues. Migration will be painful for acquired companies no matter what.
Why Mekon? Industry experience, skills range across the company, can talk about ROI, are independent, they are based locally (except Noz!).
Why the project will succeed. It must. Team is enthusiastic and motivated -- no issues with change resistance and recognized that the old system was unsustainable, already knew XML and XMetaL. Company's charter includes the phrase "debate passionately, get on board." And they did. Buy-in from the executive board was critical. Had to get senior VP to understand, support, and present to the board for approval. Early wins -- they already have demonstrable results. This is the right solution at the right time for this company.
Complexities and pitfalls
Didn't know what the end product was going to be. How do you learn what you need to when you don't know what you don't know? No in-house DITA experience, limited CMS knowledge. Also need to demonstrate results quickly while learning. Couldn't design perfect solution before starting, need to make changes during implementation. Balance between up-front research and management of progress expectations.
Content migration to DITA did not make the original timeline. Big reason for that is the "day job" -- writing content. So the initiative has to take a back seat to getting content out the door. Geographically dispersed team is difficult -- two locations haven't even looked at XML. Don't have a fully developed training structure yet.
The pilot project hasn't quite happened yet.
Preparing for migration is a horrible pain. Don't underestimate the cost of migration.
Publishing is complex, but it's taking time to get to a push-button process and it's not ready yet.
Planning to map to DITA, migrate to CMS. Will run old and new systems in parallel until they're sure that the new stuff is really working.
Need to re-architect content, integrate acquisitions, and refine and improve the process.
Business case for documentation team is very different from business case to board. The doc team's need for CMS needed to be presented in a way that would get approval.
This may not the right solution for everyone, but if it is, "get on with it."
CMS licenses -- some have high up-front cost but drop quickly per seat with bigger implementations. Others have low up-front cost but licensing per-seat doesn't drop much with greater volume. Makes cost evaluation different for different sized organization.
Another very interesting presentation. A rather aggressive timeline and the unique circumstance of lots of high-end skills (like XSLT development) in the documentation organization.
9:14 AM Permalink | |