The state of structure, 2011
Happy New Year!
In early 2009, we did a rather extensive survey on structured authoring. We asked about plans to implement structured authoring, existing implementations, biggest mistakes, and the like.
News
Once more into the breach…
Back in June, we hired Ryan Fulcher as an intern. Ryan has done great work, and has now been promoted to full-fledged consultant. Congratulations to Ryan!
The bad news, from my point of view, is that we now must look for a new intern.
Some thoughts on tekom
After a delightful week at the tekom/tcworld conference in Wiesbaden, Germany, I thought I’d capture a few impressions of the event.
First, it’s worth noting that tekom is really several events in one:
The ePub has landed! The ePub has landed!
Our Technical Writing 101 book is now available in an ePub edition. You can purchase it from our online store or get it from Apple’s iBookstore.
Talk amongst yourselves…introducing forums.scriptorium.com
Our web site now has forums for discussions of technical communication issues. We want to give you, our readers, a venue where you can set your own agenda instead of just responding to our blog posts.
Given Scriptorium’s particular interests, I expect to see a lot of emphasis on publishing automation and XML. But frankly, we don’t know exactly what might happen. Communities often develop in unexpected ways. It will be up to you—and us—to figure out what direction these forums go.
(We have an internal pool on how long before Godwin’s law is applied.)
The forums are available in our main site navigation. There are also RSS feeds so you can subscribe to a topic or category of interest. Or, if you prefer, you can get email notifications for new forum posts.
And how do we feel about this launch? We’re…perfectly calm.
Please join the conversation.
ePub + tech pub = ?
At Scriptorium earlier this week, we all watched live blogs of the iPad announcement. (What else would you expect from a bunch of techies?) One feature of the iPad that really got us talking (and thinking) is its support of the ePub open standard for ebooks.
ePub is basically a collection of XHTML files zipped up with some baggage files. Considering a lot of technical documentation groups create HTML output as a deliverable, it’s likely not a huge step further to create an ePub version of the content. There is a transform for DocBook to ePub; there is a similar effort underway for DITA. You can also save InDesign files to ePub.
While the paths to creating an ePub version seem pretty straightforward, does it make sense to release technical content as an ebook? I think a lot of the same reasons for releasing online content apply (less tree death, no printing costs, and interactivity, in particular), but there are other issues to consider, too: audience, how quickly ebook readers and software become widespread, how the features and benefits of the format stack up against those of PDF files and browser-based help, and so on. And there’s also the issue of actually leveraging the features of an output instead of merely doing the minimum of releasing text and images in that format. (In the PDF version of a user manual, have you ever clicked an entry in the table of contents only to discover the TOC has no links? When that happens, I assume the company that released the content was more interested in using the format to offload the printing costs on to me and less interested in using PDF as a way to make my life easier.)
The technology supporting ebooks will continue to evolve, and there likely will be a battle to see which ebook file format(s) will reign supreme. (I suspect Apple’s choice of the ePub format will raise that format’s prospects.) While the file formats get shaken out and ebooks continue to emerge as a way to disseminate content, technical communicators would be wise to determine how the format could fit into their strategies for getting information to end users.
What considerations come to your mind when evaluating the possibility of releasing your content in ePub (or other ebook) format?
XML for Lone Writers?
My December article for STC Intercom, XML & Lone Writers: Can They Go Together? is now available. From the conclusion:
The relatively low percentage of lone writers who have implemented XML is a logical result of the typical lone writer working environment. Although it is possible for lone writers to implement XML, a very cautious evaluation of the idea is definitely in order. Given the current status of the authoring and publishing tools, any lone writer who implements XML will need to master fairly demanding tools and technologies.
The stars of this article are the members of the Lone Writer SIG mailing list, who generously responded to a request for information.
XML & Lone Writers: Can They Go Together? (PDF, 200K)
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.
XML 101
My latest XML Strategist article, “The ABCs of XML,” is available as a PDF file (144K). This article was originally published in the September/October 2009 issue of Intercom.
The technical side of XML is not much more difficult than HTML; if you can handle a few HTML angle brackets you can learn XML. […] If […] you don’t like using styles and
prefer to format everything as you go, you are going to loathe structured authoring.
Just trying to make sure that there are no surprises. The article itself is a very basic introduction to the principles that make XML important for technical communication: automation, baseline architecture (sorry…I had problems with B), and consistency.
Liberated type
(or should that be “Liberated typoes?”)
We have opened up free access to two of our white papers:
- Hacking the DITA Open Toolkit, available in HTML or PDF (435 KB, 19 pages)
- FrameMaker 8 and DITA Technical Reference, available in PDF (5 MB, 55 pages)
These used to be paid downloads.
Why the change of heart? Most of our business is consulting. To get consulting, we have to show competence. These white papers are one way to demonstrate our technical expertise.
(By this logic, our webcasts should also be free, but I’m not ready to go there. Why? We have fixed costs associated with the webcast hosting platform. Plus, once we schedule a webcast, we have to deliver it at the scheduled time, even if we’d rather be doing paying work. By contrast, we can squeeze in white paper development at our convenience.)
What are your thoughts? We are obviously not the only organization dealing with this issue…
Is this thing on?
If you are reading this, then we have succeeded in migrating our web site over to WordPress.
Of course, the process of managing our own content always takes a back seat to working with our customers’ content, so the process took longer than you might expect.
We did learn a couple of things, most of which should sound awfully familiar if you are working on your own content strategy:
- It’s not until you try to move into a new system that you recognize all the mistakes you made the previous system.
- PHP stands for Picky Hypochondriac Programming. I had several cases where code absolutely refused to work for no apparent reason. I had the resident PHP expert (Simon) look it over. Eventually, I gave up and retyped the code, and then it worked.
- Learn to work with the tool and not against it. I have to credit a former coworker, Bruce Bicknell, for this little gem, which he originally applied to Word versus FrameMaker. When moving from Dreamweaver-based HTML to WordPress, take some time to learn best practices for WordPress. Don’t try to impose your existing Way of Doing Things onto the new system. It’s inefficient and it probably won’t work.
- Content migration is always awful. To transfer our blog, I found a blogger-to-WordPress converter. That worked pretty well, except that a couple of posts now have my name on them even though I didn’t write them. Transferring comments was a travesty that involved the support people at Haloscan (helpful) and cleaning out random comment triplication (gross manual labor).
But I hope you like the new site and blog. Please poke around and leave us feedback.
Webcast: Structured authoring survey results
June 16, 11 a.m. 1 p.m. Eastern time
I will be reprising my STC conference presentation, “The State of Structure in Technical Communication.” This webcast will discuss some of the results from our industry survey on structured authoring.
If you can’t wait that long, the report itself is available in our store.
Register for the webcast
Think global
We are joining with a couple of other technical communication companies to form the TechComm Alliance:
Three companies—Cherryleaf Ltd., HyperWrite, and Scriptorium Publishing—are forming TechComm Alliance to help us handle technical communication projects around the world. We are located in the United Kingdom, Australia, and the United States, respectively, and each company has customers in both its home location and in other countries. TechComm Alliance will make it easier to work with global companies that need services worldwide.
How will this work? We expect to:
- Work together on large projects that require support in multiple locations. For instance, Scriptorium might be implementing structured authoring for a U.S. company that also has operations in Europe and Australia. During rollout, instead of sending a Scriptorium consultant around the world, we partner with Cherryleaf for the training in Europe and with HyperWrite for the training in Australia. The result? Our customer saves on travel expenses, and our consultants spend less time in airplanes.
- Refer projects to each other. Each company has (and will continue to have) clients around the world. When we feel that a local presence would benefit the customer, we can refer the project to our alliance partners.
- Produce webinars and other events together. I’d like for Scriptorium customers to benefit from the expertise of our partners, and we are working on joint webinars.
Structured authoring in technical communication
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.”
DITA adoption increasing overall structured authoring adoption
I’m knee-deep in survey data analysis. With over 600 responses, our recent structured authoring survey was hugely successful–thank you. Many respondents added candid details about their experiences with structured authoring implementation–their fears, mistakes, and biggest surprises.
The survey report will be available later this month (free to participants, $200 for others), but I wanted to give you a couple of preliminary highlights:
- About 30 percent of respondents said that they are currently using structured authoring.
- There’s a lot of hype around DITA, but our data indicates that it’s backed up by reality. Consider this chart, which shows the top three types of structure (custom, DocBook, or DITA) implemented, being implemented, or planned.
DITA dominates the chart. But it looks as though DITA is additive. That is, it’s not cannibalizing the numbers for DocBook or custom structures. Those numbers are relatively flat. Instead, it looks as though DITA is increasing the total number of implementations.
If you are attending the STC Summit this year, I’m doing a presentation on the survey results on Monday, May 4, at 1:30 p.m., called “The State of Structure.”
What do Tech Writers Want?
Answer? I don’t know, but The Content Wrangler is conducting a survey to find out. Here’s the announcement:
2009 is a touch economic year for most of us. Companies are cutting back on nice-to-have purchases and focusing in on what’s necessary. This survey conducted by The Content Wrangler aims to help us better understand your training needs for 2009 and to identify the types of classes you need. We plan to use this information to help training providers create relevant public and on-site training programs that address your needs and to gain an understanding of the current state of training program interest in our industry today.
In case you need further motivation, there is also a random drawing for some goodies. The survey has only five questions, so it should be quick.
How to Get a Job
[update to correct bad links]
This is the best advice for job seekers I’ve ever seen. India Amos writes about her pile of resumes:
And do you want to know what’s the most striking thing about most of these hopefuls? They are completely wasting their time. And mine, of course, but mostly their own. Because they’re not only not going to get a job with me, they’re not going to get a job with anyone unless that person is as slovenly and illiterate as these applicants.
She proceeds to offer some excellent advice in numerous categories. Here are some excerpts from a lengthy list about formatting:
- Learn to use style sheets, so that you can make your heading styles consistent. If you choose to ignore my request for a PDF résumé, try to make sure your Word attachment doesn’t demonstrate to me what a slob you are, formatting everything locally and aligning text using spaces instead of tabs.
- Don’t Capitalize Everything. I Cannot Emphasize This Enough. It Makes You Look Like a 419 Scammer.
- Violet 9pt Arial is probably not a good choice for anything.
Hehe. (sob)
Related to this: How Not to Get a Job (Palimpsest, December 2007)
Of course, in today’s economy, lots of people need jobs. So here is some long-promised advice on how to get a job:
- Apply for jobs where your skillset is relevant. In this job market, with tons of job seekers, you are unlikely to get the “stretch” position. So, look for positions that are equivalent to your last position, that you are uniquely qualified for, or that you are slightly overqualified for. For instance, let’s say you are a technical writer with five years of experience and “the usual” complement of technical skills. What is your unique qualification? If you speak some Japanese, look for Japanese companies where your language skills might be useful. If your undergraduate degree is in music, look for a company that makes music software or products related to music. In other words, look for a position where your outside interests are also relevant. But, at a minimum, apply only for positions that you are reasonably qualified for. It’s tempting, especially when you really need a job Right Now, to take the firehose approach and spray resumes everywhere. It doesn’t work. Focus your job search and send out a smaller number of really good applications.
- Do your homework. Before contacting the company, investigate. Read their web site, read any recent news coverage. Look them up on LinkedIn and see if you know anyone in the organization. (You are on LinkedIn, right?) Use the information you find to make your application more relevant. If you get an interview, do more homework before the interview.
- When you apply for the job, follow the #!%$#!%#! instructions. If asked for PDF, provide PDF. If asked for Word, provide Word. Et cetera.
- Submit resumes online. Paper and snail mail takes too long. By the time your resume arrives by mail, the position could be filled. Also, dropping off your resume in person? Creepy and needy. (One exception: If you know someone at the organization and they are willing to deliver the resume for you. Even then, I would recommend sending your contact email with the resume and asking him or her to forward it.)
- Whether it is requested or not, write a cover letter. The cover letter should be the body of your email and not an attachment. Follow Ms. Amos’s excellent advice. You might also use a T letter as your cover letter, but do send the resume. Tom Murrell describes the T letter in detail in his article Get More Interviews with a T-letter. But again, I disagree with his advice to leave out the resume. If you are instructed to send a resume, send a resume.
- Show up on time for any in-person interview. If possible, do a dry run the day before to locate the building. Or plan to arrive very early. There are worse things than sitting in a nearby coffee shop for half an hour. (Don’t chug too much coffee.)
I could go on for a long time, but frankly, these six points will lift you above 95 percent of the other applicants, and you can do the rest.
(India Amos via words / myth / ampersand & virgule)
Neil Perlin starts blogging
Hyper/Word Services now has a blog, which Neil Perlin (the principal) describes as “low-gibberish overviews of online help technologies and methodologies.” The world could use some of that.
But more importantly, will Neil use his blog as a venue for updates to his Guide to BBQ Restaurants?? The world is waiting.
It’s not easy being green
Over the years, we’ve been quite smug about Scriptorium’s eco-friendly credentials. We don’t have any nasty, dirty factories, we mostly provide services, and all in all, we’re pretty clean.
On the surface.
It turns out, of course, that there are two major holes in our green company argument:
- energy
- air travel
On the energy front, we use power to heat and cool our office and to run our (many) computers. When we travel to visit customers, we usually fly, and airplanes emit huge amounts of pollutants.
In honor of our 10th anniversary, and for Earth Day 2007, we are announcing several new initiates to help reduce our environmental footprint:
- Recycling: We already recycle most of what we use in the office: paper, computers, aluminum, and plastic. We are also going to make a significant effort to use more recycled paper when we print, both in the office and with our print vendors.
- Air travel: Through carbonfund.org, we are purchasing carbon offsets to “zero out” the carbon emissions from our collective air travel. We are also offering our customers the option of live, instructor-led web-based classes, which eliminates travel requirements for client and customer alike.
- Energy: We have joined the North Carolina GreenPower program, which allows us to purchase energy from renewable sources.
You can find a list of carbon offsetting programs in several countries here. There’s an excellent overview of the concept at grist.org and carbonoffsets.org.
Friends in new places
We’re pleased to announce that we have joined XMetaL’s Partner Program as a Certified Service Provider.
We will not be reselling XMetaL software, but we will begin offering XMetaL classes this summer.
This is really a customer-driven decision — we have clients asking us to develop XML and DITA implementations with XMetaL as the core authoring tool.
Creative Suite 3
A little public information from the Adobe Training Partners Summit. Creative Suite 3 will be officially announced on March 27.
Free (legal!) Photoshop
Adobe has just announced that they will have an online, ad-supported, FREE version of Photoshop:
And now, a word from FrameMaker product management…
Posted today on the Adobe TechComm blog by Aseem Dokania, FrameMaker product manager:
I have noticed discussions on some blogs and mailing lists regarding the future of FrameMaker. Let me assure you, as the Product Manager of FrameMaker, that FrameMaker is here to stay. We would do what it takes to keep FrameMaker at the leading edge of technology.
Aseem also requests feedback, and I know my readers have opinions, so get those comments going, either here or directly on his post.
