Site FeedPalimpsest has moved. Please visit our blog in its new location for the most recent posts from Scriptorium.
Palimpsest
Authoring tools do matter
Thursday, July 09, 2009 — posted by Sarah O'Keefe
"I can write in anything.""The tool doesn't matter."
"I can learn any new tool."
Most of the time, I agree. But then, there are the exceptions.
One of our customers is using FrameMaker to produce content that is delivered in HTML. (They use structured FrameMaker, generate XML, and then transform via XSLT into HTML.) Their rationale for using FrameMaker was:
- The project was on an extreme deadline.
- The writers already knew FrameMaker.
- FrameMaker is already installed on the writers' systems.
But.
We have had a continuous stream of requests from the writers to make adjustments to the FrameMaker formatting. Things like "the bullets seem a little too far from the text; can you move them over?"
FrameMaker is being used as an authoring tool only. FrameMaker formatting is discarded on export; HTML formatting is controlled mainly by CSS. However, even after repeated explanations, we continue to receive requests to modify the FrameMaker formatting.
In this specific case, the authoring tool does matter. Writers are focusing on the wrong set of issues (leading, kerning, print formatting), none of which is actually relevant for the output.
Why are they focused on this stuff? Because they can. It seems to me that moving authors to a WYSIOO (what you see is one option) tool, such as oXygen or XMetaL, instead of a WYSIWYG tool (FrameMaker) would eliminate the obsession with irrelevant formatting.
Mandatory 80s reference:
Labels: structured authoring
11:03 AM Permalink | |
Webcast: Structured authoring survey results
Wednesday, May 27, 2009 — posted by Sarah O'Keefe
June 16,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
Labels: presentations, stc09, structured authoring
9:00 AM Permalink | |
Back from Atlanta, STC wrapup
Thursday, May 07, 2009 — posted by Sarah O'Keefe
The STC Summit was fun as always. My slides are below, but first some other observations.David Pogue was an excellent keynote speaker. And he sang!
Attendance was lower than last year, but traffic at our booth (and others from what I heard) was up. I think this was a combination of a better location for exhibitors, shorter exhibit hours (Wednesday was cut), and perhaps more senior and more serious attendees.
The biggest change from previous years had to be the use of social media in general, but especially Twitter:
- The #stc09 hashtag got a serious workout, the tweetup drew 50 or 60 people, and there was constant chatter about the conference online.
- There was a complementary online event, #stcnotthere.
- As we were leaving the conference in sketchy weather, #stuckinATL_stc09, created by @lisajoydyer, helped us chronicle the various airport delays and find each other at the airport. It made the delays almost bearable.
- Rachel Hougton's flickr feed captures the feel of the entire event, ranging from the Georgia Aquarium and the World of Coca-Cola to the honors banquet and lots of casual photos. (great job, Rachel, btw)
- You can find a collaborative liveblog on scribblelive.
Tom Johnson interviewed numerous people (including me) at the event. His interview with Ginny Redish is already available.
The tweeting and other social media augmented the actual event. There were people tweeting for lots of reasons: to solve problems (chairs needed), organize groups for dinner, provide sound bites from presentations, and more. The organizing committee put up a twitter feed on a monitor next to their booth and got lots of attention.
I get the impression that the tweets gave non-attendees a flavor of the event. If you were following #stc09 but not attending, did this make you more likely to consider attending in 2010?
Ironically, one of my presentations was actually about technical communication and Web 2.0 issues. I have a white paper on this topic, which is far more useful than the slides. (OK, if you insist, the slides are also available.)
My second presentation was presumptuously entitled "The State of Structure." This presentation discusses the results of our industry survey on structured authoring, which was conducted in January and February 2009.
The State of Structure
If you want more information, the survey report is $200 and available in our store.View more presentations from Scriptorium.
Labels: conferences, stc09, structured authoring, survey
5:02 PM Permalink | |
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: analysis, change management, dita, structured authoring, survey, white papers
5:00 PM Permalink | |
DITA isn't magic
Wednesday, February 25, 2009 — posted by Alan Pringle
The WritePoint staff blog makes a very good point about DITA: it isn't a magic wand that fixes documentation problems. Also, it's worth noting that:... DITA didn’t introduce something completely new. DITA incorporates achievements made in a wide variety of approaches to organizing content that were being proactively conducted starting from 1960’s.Don't get me wrong: DITA can be a good solution for many departments that want to set up an XML-based single-sourcing environment. Just don't expect that a twitch of your nose will convert your legacy content or make the output from the Open Toolkit match your formatting requirements.
Labels: dita, structured authoring
8:02 AM Permalink | |
Take our survey on structured authoring--and get a free report on the results
Thursday, January 29, 2009 — posted by Alan Pringle
Curious about other folks' experiences with considering, planning, and implementing a structured authoring/XML environment? Well, now is your chance to get that information by participating in our survey on structured authoring.We want input from everyone: those who have implemented structured authoring, are planning to implement it, or have decided against it. The short survey will take no more than 10 minutes of your time. The deadline for responses is March 1, 2009.
In April, we will release our analysis of the results. If you participate in the survey and provide your contact information (which is entirely optional), we will give you a free copy of the report, which will cost $200. We are also going to give a $50 amazon.com gift certificate to two randomly selected people who provide contact information. (By the way, if you provide your contact information, we will not share that information with any other company.)
Take the survey today. We appreciate your help.
Labels: structured authoring, survey, xml
8:30 AM Permalink | |
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. [...]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.
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.
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.And this interesting note in comment #20:
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.
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: analysis, change management, history, structured authoring
8:00 AM Permalink | |
Put the drawing tools down!
Thursday, December 11, 2008 — posted by Alan Pringle
This list of technical writing myths has a decidedly DITA slant; I don't necessarily like the idea of DITA driving what is and isn't acceptable practice for technical writing. That being said, I endorse the information provided about myth #4:
4. The Callouts on Graphics Myth
If you want to reuse the same graphic in multiple publications and even multiple languages, it is a good practice not to put callouts in the source file of the graphic itself. Instead, you place your callouts "on top of" your graphic in your text editor (Word) or DTP program (InDesign, FrameMaker, ...). This is not supported in DITA. Therefore, if you need to use callouts in graphics, try to use language-independent ones (A, B, C...) in the source file of the graphic and put the explanation of these callouts in a table below the graphic in your DITA XML content. [Yves Barbion]
It's not just the DITA standard that doesn't support callouts placed with a document processor's drawing tools. We have a client for whom we created a custom XML structure for FrameMaker content, and that content contains many graphics with callouts. The client translates the content into multiple languages.
In the previous workflow in unstructured FrameMaker, the client placed the callouts in the anchored frame with FrameMaker's drawing tools. However, if you do that in a structured FrameMaker workflow and save content out to XML, FrameMaker by default saves each image with added callouts into a new CGM graphic file that no longer has editable callouts. There can't be complete round-tripping between XML and FrameMaker because the graphics aren't preserved in this scenario.
Therefore, the rule for this client is that an anchored frame can contain just one image file imported by reference. Period. No other text, text frames, or anything. If callouts are necessary, they are included as part of the source graphic; the client adds numbered callouts in Illustrator. A numbered list specifically for explaining those callouts follows the graphic.
The XML generated from FrameMaker points to the image files, and FrameMaker doesn't need to generate new graphic files to include any callouts added with FrameMaker's drawing tools. (If the directory containing XML files includes a CGM file that FrameMaker created during export, that usually means there is an anchored frame somewhere that contains something more than just a referenced image file.) Another huge plus: because the callout explanations are part of the text, they are translated without changing the original graphic.
Separating callouts from your images and making them part of the text is smart for any workflow because of localization issues, and it pretty much becomes mandatory when you're establishing an efficient structured authoring environment (and not just those based on DITA).
P.S. One other thing to think about with graphics in structured authoring environments: if you use XSL to transform your XML into online formats, determine if web-ready graphics (such as PNG files) will work in your print/PDF and online content. If so, you eliminate the need to convert images to formats for online viewing.
Labels: dita, FrameMaker, localization, structured authoring
9:00 AM Permalink | |