Author Archive

Lessons learned on the way to the office

October 12th, 2009 by Sheila Loring

In what now seems like a previous lifetime, I began my college career studying fine art. I chose this program because I’d been drawing incessantly for years and managed to secure an art scholarship. I had no idea what I would do with the degree, I just knew I loved drawing and studying art history.

I specifically remember the turning point in my college career as an artist. The assignment was to draw a supersized version of any object. For some reason, I chose a hamburger. (More on that choice later.) So I took great pains to capture every detail–fresh water drops on the lettuce leaves, the oozing slice of cheese, the thick, juicy meat patty, the sesame seeds on the bun. I thought it looked pretty realistic.

Photo by Rob Owen-Wahl
Rob Owen-Wahl / stock.xchng

The instructor’s assessment haunts me to this day. He said it was the most disgusting, unappetizing hamburger he’d ever seen. (He was NOT a good professor.) My classmates froze in silence, hardly believing his cruel response to a fledgling artist’s precious work. I was heartbroken and humiliated. After such a traumatic event, no wonder I became a vegetarian.

That was a turning point for me. I decided to switch majors to English literature because I loved to read. Again, I had no idea what I would do with an English lit. degree, which is not an uncommon situation. If you took one class in English lit., you know how many essays students have to write and the “valuable” feedback one gets from the professors. That experience prepared me for what would come later.

Years after graduating and working in dead-end jobs, I made my way into technical writing and consulting, and the rest is history. Now I get feedback from editors and customers, and it actually is (mostly) helpful. Plus, I get to learn about new tools and technologies on a regular basis and hang around with other cool technical writers.

Am I ever glad I switched majors.



The long and winding roads from DITA to PDF

August 21st, 2009 by Sheila Loring

DITA XML is of little use to readers unless it’s converted to some kind of output. The DITA Open Toolkit (DITA OT) provides transforms and scripts that convert DITA to PDF output and a long list of other formats.

Producing PDF output from DITA content can be challenging. DITA XML is converted to an XSL-FO file, a combination of content and formatting instructions. You must know XSL-FO to customize the PDF, even just to add simple content such as headers and footers, logos, and so on.

To forgo the programming, you can choose a page layout or help authoring tool, but these tools also have pitfalls. Page layout programs have varying degrees of DITA support. Help authoring tools let you style the PDF through CSS, but you can’t fine-tune page layout as you can in page layout programs.

These are just a few examples we discuss in our white paper “Creating PDF files from DITA content.” Read the white paper online (in HTML or PDF).



Top five reasons to like XMetal and OXygen

June 11th, 2009 by Sheila Loring

Full disclosure: We’re an XMetaL Services Provider and have no particular affiliation with oXygen.

I’m in the fortunate situation of having access to both XMetaL 5.5 and oXygen 9.3. Both are excellent XML editors for different reasons. I’d hate for Scriptorium to make me choose one over the other.

From the viewpoint of authoring XML and XSLT, here are my top five features of both editors:

oXygen

  • Apply XSLT on the fly: You can associate an XML file with an XSLT and transform the XML within oXygen. Goodbye, command line! XMetaL will convert the document to a selected output format. You don’t choose the XSLT–it hasn’t been a big concern for me.
  • Indented code: The pretty-print option makes working with code so easy. You can set oXygen to do this automatically when you open a file or on demand. The result is code indented according to the structure. XMetaL doesn’t have pretty print.
  • Autocompleting tags: As you type an element, oXygen pops up a list of elements beginning with the typed string. You press Enter when you find the right tag, and the end tag is inserted for you. The valid attributes at any particular point are also shown in a drop-down list. XMetaL doesn’t have autocompleting tags.
  • Find/replace in one or more documents: I’ve often needed to search and replace strings in an entire directory. In XMetaL, you can only find and replace in the current document.
  • Comparing two documents or directories: Compare files by content or timestamp. In a directory, you can even filter by type so only XML files, for example, are compared. XMetaL doesn’t offer this feature.

XMetaL

  • Auto-tagging content: You can copy and paste content from an unstructured document (a web page, for example), and XMetaL automatically wraps the content in elements. Even tables and lists are wrapped correctly. This can be handy if you have a few documents to convert. In oXygen, the content is pasted as plain text.
  • Auto-assignment of ID attributes: Never worry about coming up with unique IDs. XMetaL will assign them to the types of elements you select. Warning: The strings are quite long, as in “topic_BBEC2A36C97A4CADB130784380036FD6.” oXygen only inserts IDs on the top-level element but full support will be added in version 10.3.
  • Auto-insertion of basic elements: When you create a document, XMetaL inserts placeholders for elements such as title, shordesc, body, and p. It’s a small convenience. oXygen will also insert elements if you have Content Completion selected in the Preferences.
  • WYSIWYG view of tables: The table is displayed as you’d see it in a Word or FrameMaker document. In oXygen, all you see are the table element tags.
  • Reader-friendly tag view: The tags are a bit easier to read in XMetaL than oXygen. In XMetaL, the opening and closing tags are displayed on one line when possible. This feature saves space on the page and makes the document easier to read in tag view. For example, you might have a short sentence wrapped in p tags. In XMetal, the p tags are displayed on the same line. In oXygen, the p tags are always on separate lines. This is another convenience that doesn’t sound like a big deal, but it really makes a difference while you’re authoring.

oXygen and XMetal have so many other strengths. I’ve just chosen my top five features.

What I’d like to see in XMetaL: The ability to indent code, the ability to drag and drop topics in the map editor.
What’s I’d like to see in oXygen: The ability to view a table–lines and all–in the WYSIWYG view instead of just the element tags.

So how do I choose which editor to use at a particular moment? When I’m casually authoring in XML, I choose XMetaL for all of reasons you read above. The WYSIWYG view is more user-friendly to me. But when I’m writing XSLT or just want to get at the code of an XML document, oXygen is my choice.

Get the scoop on oXygen from http://oxygenxml.com. Read more about XMetaL at http://na.justsystems.com/index.php.

Update 6/15/09:
I’m thrilled to report that two deficiencies I reported in oXygen 9 are now supported in the latest version of oXygen — 10.2.

  • In Author view, tables are now displayed in WYSIWYG format. Just like in your favorite word processor, you can drag and drop column rulings to resize columns. After you resize columns, the colwidth attribute in the colspec element is updated automatically. This is much easier than manually editing the colwidth.
  • In Author view, the tags are now displayed on one line when possible. Before, the tags were always on separate lines from the content.

Two more reasons to love oXygen!



A different take on Twittering and technical writers

June 2nd, 2009 by Sheila Loring

Technical writers abound on Twitter as do blog posts on how Twitter can make you a better tech writer.

I’d Rather Be Writing has an alternate take in the article Following the NBA Can Make You a Better Writer. Tom Johnson uses the analogy of Kobe Bryant and Lebron James playing their respective positions on the court. He argues that unless you’re a one-person shop, you’re doing yourself a disservice by trying to be a Jack- or Jill-of-all-trades. Play up your strengths, and minimize your weaknesses, tech writers. Read Tom’s article for more.



How Twitter makes you a better writer

April 1st, 2009 by Sheila Loring


To Twitter or not to Twitter? That’s the question many technical writers I know face these days. Critics say writing in 140 characters or less is ruining our ability to communicate effectively and follow grammatical rules.

In the following article, Jennifer Blanchard argues that Twittering actually improves your skills as a writer:

http://www.copyblogger.com/twitter-writing/



Adobe Photoshop Express

March 20th, 2009 by Sheila Loring

Photoshop Express is a photo editing and sharing web-based application. You can store up to 2GB of photos for free. Accounts are available for $19.99 (20GB), $39.99 (40GB) or $99.99 (100GB) per year.

You can either upload photos or log in to your Facebook, Flickr, Photobucket, or Picasa accounts and edit the photos directly. When I logged in to Flickr and Facebook, my albums all appeared in Photoshop Express along with the descriptions. The tags didn’t make it for some reason though you can tag the photos in Express, but still, I like the Web 2.0 integration.

The typical editing options are available — sharpen, crop, rotate, red-eye, white balance, hue, etc. It’s very similar to Picasa. You can email and link to photos, order prints through Shutterfly, and decorate with cute objects, costumes, conversation bubbles, and other stock graphics.

Once you share photos, friends and family can visit your account online.

Photoshop Express is worth checking out if you don’t want to pay for Photoshop Elements (my personal favorite) or Photoshop and want to edit photos on social network web sites. The editing features are more robust than Flickr (but similar to Picasa). The main downsides are lack of online community (like that of Flickr) and expense. (I get unlimited online storage at Flickr for $24.95/year.)

Update March 21, 2009
I love the integration of Photoshop.com and Photoshop Elements. I can create an album in Photoshop Elements, upload it to my Photoshop.com account, and easily order prints. Cool! Other programs offer this feature, but I’ve never used it in Elements. I’ve only used Elements to organize and edit photos.