Random thoughts about publishing

Site Feed

Labels

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

Palimpsest

 

Webinar mania!

Tuesday, June 09, 2009 — posted by Sarah O'Keefe

I have several webinar-related updates to share:

Next week, the State of Structure

You probably know that Scriptorium conducted an industry survey on structured authoring earlier this year. The report, The State of Structure in Technical Communication, is available in our online store for $200.

There is a cheaper option to get the highlights. On Tuesday, June 16, at 1 p.m. Eastern time, I'll be delivering a one-hour webinar that highlights the most important findings.

Coming in July and August

Expect to see additional webinars in cooperation with our TechComm Alliance partners, Cherryleaf and HyperWrite. We are also welcoming Jack Molisani of ProSpring, who will offer excellent and candid career development advice. Watch this space for details about these upcoming events. Scriptorium consultants will also be offering additional content.

Recorded events

Two of our recent webinars are now available for download:

• Hacking the DITA Open Toolkit
  
• Documentation as Conversation
  

Each webinar lasts about one hour and is $20, either live or recorded. You can register for the Tuesday webcast and download recordings in our online store.

(Warning: The recorded webcast files are quite large.)

Labels: presentations, webcasts

10:08 AM Permalink | |

 

Webcast: Structured authoring survey results

Wednesday, May 27, 2009 — posted by Sarah O'Keefe

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

Labels: presentations, stc09, structured authoring

9:00 AM Permalink | |

 

Documentation as conversation webinar

Friday, May 22, 2009 — posted by Sarah O'Keefe

We have added Documentation as Conversation, presented by Anne Gentle, to our upcoming webinars. Anne is scheduled to present on June 9 at 11 a.m. Eastern time:

Even if your documentation system does not converse with your users, your documentation can help customers talk to each other and make the connections that help them do their jobs well or learn something new as if they were in a classroom with a community for classmates. This talk describes how you can think about documentation and user assistance in a conversational way, with the help of social media technology. I'll discuss the topics in my new book, Conversation and Community: The Social Web for Documentation. I'll describe the use of in-person Book Sprints that combine wikis and community events to gather together writers to accomplish documentation goals

Anne is an expert, perhaps the expert, on using wikis and other social media to extend traditional documentation efforts. She's also an excellent speaker, so I hope you'll join us for this session.

Register for Documentation as Conversation ($20)

See all upcoming webinars

PS We are working on additional topics and looking for more speakers. Do you have topics you would like us to cover? Please let us know. We are working on a couple of sessions on document conversion.

Labels: presentations, web 2.0, wiki

8:38 AM Permalink | |

 

DocTrain's demise and a challenge to presenters

Monday, May 18, 2009 — posted by Sarah O'Keefe

Unfortunate news in my inbox this morning:

I regret to announce that DocTrain DITA Indianapolis is cancelled. DocTrain/PUBSNET Inc is shutting down.

As a business owner, messages like this strike fear in my heart. If it could happen to them...gulp. (This might be a good time to mention that we are ALWAYS looking for projects, so send them on over, please.) My condolences to the principals at DocTrain.

Meanwhile, I'm also thinking about what we can do in place of the event. I had a couple of presentations scheduled for DocTrain DITA, and Simon Bate was planning a day-long workshop on DITA Open Toolkit configuration.

So, here's the plan. We are going to offer a couple of webinars based on the sessions we were planning to do at DocTrain DITA:

• Demystifying DITA to PDF Publishing, June 2, 11 a.m. Eastern time (Sarah O'Keefe)
  
• Hacking the DITA Open Toolkit, June 4, 11 a.m. Eastern time (Simon Bate)

Each webinar is $20. We may record the webinars and make the recordings available later, but I'm not making any promises. Registration is limited to 50 people.

Here's the challenge part: If you were scheduled to present at DocTrain DITA (or weren't but have something useful to say), please set up a webcast of your presentation. It would be ultra-cool if we could replicate the event online (I know that the first week in June was cleared on your schedule!), but let's get as much of this content as possible available. If you do not have a way to offer a webinar, let me know, and I'll work with you to host it through Scriptorium.

And here's my challenge to those of you who like to attend conferences: Please consider supporting these online events. If $20 is truly more than you can afford, contact me.

Labels: dita, DITA Open Toolkit, doctrain, PDF, presentations

4:13 PM Permalink | |

 

DITA webinar now available...

Tuesday, February 10, 2009 — posted by Sarah O'Keefe

Labels: dita, presentations, xml

10:48 AM Permalink | |

 

Beat the post-holiday blahs

Wednesday, December 03, 2008 — posted by Sarah O'Keefe

It's never too early to start thinking about fun things to do in February.

On Thursday, February 5, 2009, at 9 a.m. Pacific Time (noon Eastern time/5 p.m. London time/etc.), I'll be offering a webinar in conjunction with Madcap Software. Not sure this qualifies as "fun," but it's better than complaining about the weather, which is our major activity here in late winter.

DITA 101: Why the Buzz? DITA, the Darwin Information Typing Architecture, is the new buzzword in technical communication. But why? In this webinar, you'll learn about DITA concepts, business case, and typical scenarios where DITA is used.

You can then evaluate for yourself whether DITA makes sense for your content. Best of all, the webinar is free, which is the right price in this economic climate.

If you are not at all familiar with DITA and want some introductory information, join me for this session.

The webinar is free, but registration is required here.

Labels: dita, madcap, presentations, xml

8:00 AM Permalink | |

 

Presentations on features squeezed into FrameMaker 8

Thursday, November 20, 2008 — posted by Terry Smith

Just two weeks ago I was in an elementary school gymnasium working as an election official. Fourteen straight hours with no breaks for meals because officials aren't allowed to leave the polling area (which is why your ballot may have crumbs on it, sorry about that). In my precinct one candidate received only one vote more than the opponent; in another race, the difference was six votes. A very long and exciting day.

Bleary-eyed but pleased to have served my precinct, I spent the next two days attending the DITA/TechComm conference. Perhaps not the heady stuff of this year's election, but definitely worthwhile. This conference had two themes: DITA and the tools in the Adobe Technical Communication Suite (although Madcap Flare was definitely represented, too). The place where those two topics meet is FrameMaker.

I was scheduled to speak on two FrameMaker topics for the conference. FrameMaker 8 now has built-in DITA authoring capabilities, which I demonstrated. I had a few slides to keep the demonstration on track. The slides, which I have included here, are brief.



My recommendation? If you want to get the most from FrameMaker's conditional text capabilities, use structured FrameMaker and install the free ABCM product instead of using FrameMaker 8's Filter By Attribute feature.

Labels: adobe, conferences, dita, FrameMaker, PDF, presentations, xmetal

11:49 AM Permalink | |

 

Learning the DITA Open Toolkit

Thursday, September 04, 2008 — posted by Sarah

(Scriptorium Publishing is a JustSystems Services Partner.)

Simon Bate's webinar, An Overview of the DITA Open Toolkit, is now available. 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.

Are you currently...? (choose one)

• 31%, Using XML
• 32%, Transitioning to XML
• 16%, Planning to transition
  
• 17%, Considering a transition
  
• 3%, Not considering it at all
  

If you answered "using XML" above, what content model do you use? (choose one)

• 59%, DITA
• 0%, DocBook
• 1%, Other publicly available
  
• 10%, Developed in-house
  
• 3%, Not considering it at all

Probably not too surprising that DocBook scored 0% in a DITA-specific presentation.

I liked the last poll:

What formats do you currently or plan to publish to?

• 50%, print
  
• 92%, PDF for download
• 49%, web site
  
• 79%, online help
  
• 18%, other
  

92% are delivering PDF. We very frequently have people tell us that they "don't need print," but it nearly always turns out that they do need PDF. We operate on the general assumption that all of our customers are going to need PDF at some point, even if they don't think so, and I'm happy to see at least one data point that supports this line of thinking.

The problem, from our customers' point of view, is that producing nice PDF from DITA content is really quite challenging. (From our point of view as consultants, this is not necessarily a bad thing.) What makes PDF so challenging? Basically, you are reverse engineering your layout engine (think FrameMaker or InDesign) in the XSL-FO programming language.

Simon's presentation provides an excellent introduction to the Open Toolkit, which many find quite intimidating. This was apparent from some of the questions and comments that Simon got:

Is there a GUI for OT that could be used by documentation production staff rather than command line?

I haven't typed a command into DOS in twenty years.

What's the difficulty level of using OT to get HTML output that is more professional-looking, like a WebWorks HTML generation?

Can you please define the purpose of ANT files?

It's worth noting that running the Open Toolkit is vastly less difficult than configuring the Open Toolkit. The person doing the configuration work will need to understand Ant, type DOS commands (!), and rework the default transformation templates to produce the desired output. The person generating output with the configured OT will need to type in one command or just double-click a batch file to start processing.

Many of our customers have turned to us for the Scary Configuration Bits. If you're looking for help, keep us in mind.


This session was the second in a series of three webinars we are doing jointly with JustSystems. The last session, on September 23, will provide more details on customizing the DITA Open Toolkit. The webinar is free, but advance registration is required here. Hope to see you there.

Labels: dita, presentations, xmetal, xml

3:41 PM Permalink | |

 

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)

• 31%, Word
• 14%, HTML authoring tool (i.e. Dreamweaver)
• 69%, Desktop publishing tool (i.e. unstructured FrameMaker, PageMaker, InDesign)
• 20%, Help authoring tool (i.e. RoboHelp, Flare, AuthorIT)
• 37%, XML authoring tool (i.e. XMetaL or structured FrameMaker)
  

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: change management, presentations, xmetal, xml

11:27 PM Permalink | |

 

English lessons

Wednesday, June 25, 2008 — posted by Sarah

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.

I had some very interesting discussions with participants at both events, ate a lot of great food, and had a generally wonderful time.

Labels: conferences, presentations, stc2008, xpubs

4:26 AM Permalink | |

 

WritersUA: Day 3, Morning

Wednesday, March 19, 2008 — posted by Sarah

Dave Gash (hypertrain.com) leads off the festivities with a discussion of the UA Holy Grail. And no, it's not DITA.

He is discussing True Separation of Content, Structure, Format, and Behavior.

Interesting, because we normally hear about separation of content and presentation -- he's making finer distinctions.

According to Dave, the current authoring method is to using WYSIWYG and code editors, often in combination. And as we work, we insert what's needed wherever it's needed. The result is that documents work -- once -- but are very difficult or impossible to update, maintain, and control.

Spaghetti-code documents make our own jobs harder.

The conventional wisdom is to separate content and formatting. Content is "stuff on the page"; therefore format must be "everything that is not content."

Content could include HTML, CSS, and JavaScript. Separating out CSS still leaves "junk" in the content pages.

Dave proposes a more refined model: content, structure, formatting, and behavior.

* Content is XML
* Structure is XSLT
* Format is CSS
* Behavior is JavaScript (JS)

This will be more maintainable, which means:

* Ability to change any components without breaking the others
* Ability to reuse any component in other pages or projects
* Ability to control each component's resource allocation (that is, who creates each piece?)

How to improve your pages:

1. Identify and externalize JS behavior.

* Find the embedded scripts (<script> tags) and remove them with a reference to an external foo.js file.

<script language="javascript" src="foo.js"></script>

2. Identify JS behavior that could be CSS and convert it to CSS rules.

"If you can encode with CSS and make it declarative instead of procedural, you're way ahead of the game."

* Catch "sneaky" JavaScript behavior, such as mouseover events, that could be CSS rather than JavaScript. Event handlers that call JavaScript almost always start with "on" -- easy to identify and many can be replaced with CSS hover pseudoclasses.

.expterm:hover {font-style:italic; }
.expterm {text-decoration:none;}

Removing the code from the HTML greatly simplifies the page.

3. Identify and externalize CSS styles, recode any local formatting as classes.

Get rid of "deprecated tags and doo-doo like that."

Get rid of style attributes, font tags, b tags (become span tags).

"It's said that comments are for someone who comes behind you six months later and needs to update your code. This is not true. Comments are so that YOU can figure out six months later what you were doing in the code."

So you should comment your code.

4. Semantically mark up content as XML.

Dave's definition of semantic markup? "call things what they are."

5. Identify desired HTML output structure, write XSL transforms to produce it.

So...what's in it for me?

Discrete, maintainable, controllable components
* you can change one component without breaking others
* You can share components with other pages
* You can separate work load by skill sets
* Set it and forget it! (for everything except the content)

Code examples are available at Dave's web site: www.hypertrain.com

Questions about tools. No, he won't recommend tools. Question about schemas...Dave says the first thing that comes to mind is...DocBook???

Yikes. In an answer to a question about print and XSL-FO, somebody recommended asking....me! (I swear I didn't pay her for that, and I don't think she even knew I was in the room. Quite surreal.)

##

My only disagreement with this session is with the separation of XML as "content" and XSLT as "structure." It's my opinion that the XML includes the structure, and XSLT just gives me a way to express that structure into HTML or other formats.

I also question some of his tag names, such as <expander> for a term/definition group. The expander tag name is really a description of the desired behavior (expandable text) rather than the semantic function of the content (definition of a term). I would probably choose something like <glossaryitem> for the container, leaving opening the option of changing the behavior to something other than expansion in the future. Same quibble with <ddblock> (drop-down block).

I do like the use of the tag name for step results.

Great presentation from an energetic presenter whose motto is, "If I have to be awake, you do, too!"

Side note: I'm pretty sure that if you tied Dave's hands behind his back, he would lose his ability to speak.

Labels: presentations, writersua2008, xml, xsl

1:16 PM Permalink | |

 

Timely advice on the way to Minneapolis

Friday, May 11, 2007 — posted by Sarah

Over at Escape from Cubicle Nation, you'll find some great presentation advice in Compulsive obsession with details will save your neck when giving presentations. Most of these pointers are related to setup and configuration (rather than the actual presentation delivery), and they are based on a set of axioms:

• Materials shipped ahead of time might not arrive
• Your laptop could blow up at any time
• Classrooms or conference rooms are never set up the way that you request
• [...]
  
• If you bring only one set of clothes, you will rip or spill coffee on them

Read the whole thing for some advice on how to lower your stress level and improve the chances of a presentation going well.

For more on great presentations, check out Guy Kawasaki's post on the 10/20/30 rule for PowerPoint. And presentationzen.com. In particular, don't miss PowerPoint: sometimes you have to laugh to keep from crying.

Off to clean up my slides...

Labels: presentations

9:50 AM Permalink | |

© 2009, Scriptorium Publishing Services. Legal Stuff