Structured authoring for everyone  Clip to Evernote

Chances are, I don’t need to introduce you to the concept of structured authoring. If you do need an overview, read this.

While the concepts of structured authoring are more than just slightly useful for technical writing, they can be beneficial for just about any writing task within an organization. Think about all of the documents that you’ve read on the job and how structured, or not, they were.

Continue reading

Open Source and tech comm: another view  Clip to Evernote

Although we’ve already covered this topic, it’s nice to see that the idea of using Open Source software for documentation is gaining a bit more traction in the tech comm world. This time ’round, it’s a session at the 2009 WritersUA conference. Well, at least part of the session. It’s not one that Aaron and/or I are giving …

In case you’re wondering, the session is titled “Exploring Open Source and Alternative Tools”. You can read more about it here. On the Open Source side, the session will explore OpenOffice.org, LyX, Scribus, Inkscape, and The GIMP.

The session looks interesting. I’ll have to check out the slide deck and the conference reports in the blogosphere when both are available.

Are all XML editors for developers?  Clip to Evernote

That’s the question that was begged (at least, in my warped POV) in this blog post at oreilly.com. The author of the post wrote:

As good as oXygen is, it is not made for non-technical users. There have been attempts, especially in the land of publishing, that have proven to be fruitful. But, a generic XML editor that works reasonably well for non-technical users seems to be a myth.

He adds:

The lack of options doesn’t really surprise me because the infinite possibilities for XML seems prohibitive when creating an editor. The essence of an editor would be to maintain some constraints while keeping the markup behind the scenes.

Is the situation that bad, at least for people in our wacky little profession? Not really, IMO. There are a handful of good XML editors that are well-suited for what technical writers do. XMetaL, XMLmind XML Editor, Syntext Serna, and even oXygen to name a few. They support the XML schemas that we generally use — like DocBook, DITA, and TEI — and offer a WYISWYM authoring view that keeps “the markup behind the scenes.” On top of that, most of these editors aren’t that expensive.

What XML editor do you use? Feel free to leave a comment.

Which format for diagrams?  Clip to Evernote

I’ve been thinking about this for a while, and really haven’t been able to decide. As far as screen captures go, I’ve been using PNG for over 10 years and it’s worked well. PNG offers a great balance between the size of a file and its colour depth. And you don’t have to worry about artifacting or other nastiness that comes with JPEG.

But it’s images like flowcharts, diagrams, and other illustrations that have been on my mind. Formats like PNG are OK, but not spectacular. TIFF and BMP offer good resolution, but their way too big. EPS … well, I’ve never had much luck with that format.

Over the last few years, I’ve seriously considered Scalable Vector Graphics for illustrations. It’s an open format, many graphics applications — both free/Open Source and commercial — support it.

So, an open question: what format(s) do you recommend for illustrations in documentation? Keep in mind these criteria:

  • The format should offer good resolution and colour depth, either in print or electronic format
  • It should transfer online easily
  • The file shouldn’t be excessively large
  • You should be able to scale the images in that format with little or no distortion

Feel free to leave a comment.

OpenOffice 3.0 released  Clip to Evernote

OpenOffice 3.0 was released yesterday to the masses, resulting in their website crashing. As of this post, their website is still down. I was able to download a copy of the Windows version (insert punchline here) and I’ll be evaluating the release over the next few weeks. The company I’m currently working for uses OpenOffice to develop technical documentation and there is some interest in migrating.

Initial reviews suggest that although the UI is still a bit clunky, the performance has significantly improved from the previous version. So, given the state of the economy, will companies increasingly choose open source applications such as OpenOffice as a way of trimming the balance sheet?

Time tracking and the contractor  Clip to Evernote

It’s a necessary evil of being a contractor or freelancer: you need to keep an accurate account of the time you’ve spent on a project. Otherwise, the folks who are using your services might be more than just a little reluctant to pay you. It makes sense from the employer’s perspective: they want to know what they’re spending their money on, and simply saying “I worked 78 hours on project X” doesn’t always cut it.

So, what can you do to accurately account for your hours? Some firms use one time-tracking tool or another. If you can, use that. Or, if you prefer to use something under your control there are a lot of options out there. Just remember to keep it simple, and keep everything transparent.

Here are a few options.

Continue reading