Category Archives: authoring

by Scott Nesbitt

HTML, CSS, and printing  Clip to Evernote

If you’ve ever printed a Web page or a portion of an online document (don’t deny it, we all have), you’ve probably noticed that in many cases along with the text you get other superfluous page elements like navigation and ads. They can take up a lot of space, and cause the text on a page to wrap badly.

It doesn’t have to be this way, though. Cascading Style Sheets (CSS, which enable you to change the look and feel of Web content) also enable you to style documents for printing. Using CSS, you can change the layout of a Web page and leave out any content — like navigation or even graphics.

Doing this is pretty easy. The following are good introductory guides on how to work with CSS for printing:

Even if you use an authoring tool that automatically generates printer-friendly CSS, the content of these articles is useful if you ever need to modify the CSS code.

by Scott Nesbitt

Explaining component content management  Clip to Evernote

You may have heard the term component content management but you’re probably wondering what the term means, and what it means to you. This article — written by Paul Trotter, CEO of Author-it Software Corporation — is a very detailed look at component content management.

You might also want to take a listen to an interview that I did on this subject with Chip Gettinger of Astoria Software.

by Scott Nesbitt

Loving and hating Flare  Clip to Evernote

Tom Johnson has been working with Madcap Flare for a while now, and has published a blog entry detailing the things he loves and hates about it.

What Tom describes can be categorized as more of a like/dislike relationship than something as intense as love and hate. But he gets to the core of some of the great features of Flare, and some of the wonkiness of the product. And Tom did it the right way: he took the time to get to know Flare. As I wrote elsewhere, that’s the only honest way to review a product.

That said, we have to keep in mind that Flare is a relatively young product. It’s going through some teething pains. And, as I understand it, the folks at Madcap Software listen very carefully to their users, and (I hope) will eliminate or at least smooth out the 31 issues that Tom pinpointed. At the same time, I hope that they’ll improve upon the 45 things that Tom likes about Flare.

To be honest, though, I’m sure that Flare will always contain some features or functions that don’t appeal to everyone. No matter how much you love a piece of software, there will always be something about it that annoys you. I get frustrated sometimes with FrameMaker and OpenOffice.org Writer — and I’m a big fan of both.

by Scott Nesbitt

All about Flare  Clip to Evernote

In a recent podcast, Tom Johnson spoke with Paul Pehrson about Madcap Flare. It’s a wide-ranging discussion that touches not only on Flare and help authoring in general but also some interesting career advice.

What’s refreshing about this is that Pehrson isn’t an employee of Madcap Software. He’s a user of Flare. Well, Pehrson is more than just a user; he’s a really passionate user. He’s an MVP in Madcap’s forums and he regularly helps other Flare users solve problems.

by Scott Nesbitt

Can lightweight markup languages be used for documentation?  Clip to Evernote

Over the last few weeks, I’ve been thinking about and using markup languages quite extensively. Not the markup languages that you normally associate with documentation — like HTML, XML, or even LaTeX. I’ve actually been doing some work with lightweight markup languages, specifically one called Markdown. My focus has been using Markdown to write articles and blog posts (including this one); you can read more about my adventures with Markdown here.

Continue reading →

by Scott Nesbitt

Topic oriented authoring: a visual analogy  Clip to Evernote

Further to my previous post on whether or not DocBook is dead, Norm Walsh has an interesting and detailed comparison of topic-oriented and narrative style documentation. He uses a very interesting analogy: Van Gogh’s painting Starry Night. You have to read the posting and see the accompanying graphics to fully grasp the analogy.

Walsh makes an interesting point in this post: writing topic-oriented documentation isn’t as easy as it sounds. That’s not to say that you shouldn’t try it, but don’t expect it to be smooth sailing or the panacea to all your documentation ills.