smurphy – Page 23 – Tech, writing, and tech writing

Book Review: Documents, Presentations, and Workbooks by Stephanie Krieger; O’Reilly Media

Documents, Presentations and Workbooks Book Cover I recently joined the O’Reilly Blogger Review Program, and the first book I downloaded to review was this one: Documents, Presentations, and Workbooks: Using Microsoft Office to Create Content That Gets Noticed by Stephanie Krieger. For the most part, I really enjoyed it – it’s a huge book with a vast amount of useful information, and it’s made me more interested in working with Office than I have been in most of the past decade.

One particularly nice feature of the book is that it’s written to cover both Microsoft Office 2010 on Windows and 2011 on Mac, each of which does things slightly differently. Each version also has some special platform-specific features you won’t get in the other one, so it’s useful to know when you can achieve something interesting by switching platforms (if you have that option). I think this may be the first book on Office I’ve read that’s dual platform – I hope it won’t be the last.

Another thing that appealed to me, as a Tech Writer, was that the author included plenty of pointers on documentation best practices, rather than making it all about the tools and features. I hate when tool advocates recommend doing something really fancy, just because you can, rather than because it adds anything to the doc.

A top tip from the author is her recommendation that if something is too hard to achieve in the software, maybe you shouldn’t be doing it. She advises to investigate whether there’s a more straightforward way to achieve the same thing, and to undo and start over when things get too complicated. “Always use the simplest option for any task.” Wise advice. Especially if you’re producing a document that will be maintained in the long term. She also goes into explaining how the software actually manages a document managing formats, objects and stories. Knowing all this is a great advantage when deciding how to structure a document and understand how and why Word does what it does to the content later.

She also has advice on identifying the most appropriate tool for the job, depending on what content you want to present (including when PowerPoint might be the best choice for producing a book, rather than Word), how to transfer/re-use data between programs (and from 3rd party programs) effectively, how to reinforce style and brand, and how to present information in the way that will maximize its value to the intended audience. It’s not all “the tool lets you do X, so you should do X”, it’s more “the tool lets you do X, but you’d be mad to do that instead of Y, which is more straightforward and logical.”

There are plenty of practical tips on using the tools too. Here are just a few of my favourites, ranging from trivial to less trivial:

Customizing existing ribbons, or better yet creating your own custom ones.
Knowing that the undo cache is preserved for each Excel/PowerPoint 2010 document you’re working on when you save, so you can resume undo-ing next time you open. This is a really nice feature, and I wish every product included it.
Using SkyDrive (or SharePoint) and Office Web Apps for remote access and to share projects with multiple authors/editors. (If multiple authors work in parallel, the area each author is currently working on is blocked for other authors.) Potentially useful, though I found SkyDrive a bit flaky when trying it out. I’ll certainly use it again, though, for non-critical stuff.
Usefully, the author lists what features will and won’t work when editing different file types using Web Apps, which could save on a lot of head scratching and frustration.
Using Broadcast Slide Show to deliver a presentation over the web.
Using Backstage view to check what hidden/personal information you’re sending out in your docs.
Applying and customizing themes to reinforce branding across documents.
Using Picture Tools to manipulate images in situ instead of editing them in a graphics package first. There are a lot of nice effects and tools available.
Recovering earlier versions of a document, or even – get this – documents you closed without saving! I love this!

There were only two things about this book that I didn’t like, and the first is half-praise, half-criticism:

I found out about so many Office features I’d not used before, and that I just had to try out right away, that it took me forever to get through the book. In fact, at the time of writing this review, I have to admit I’m still not done.
For the most part, I read the book on a Kindle, which wasn’t an ideal format. It was frustrating to read a book on good presentation which wasn’t ideally presented itself. I’ve found this to be a generic problem with technical texts, though. Graphics were indistinct, tables ran outside the screen area, and notes took up sufficient screen space that they distracted from the flow of the main text. It was also difficult to dip in to the text and pick out interesting items to look at in isolation.
The PDF is much prettier, and in traditional print I’m reckon it would’ve been a quicker, easier read.

All in all, it’s a good read, and worth a look. While it wouldn’t persuade me to discard FrameMaker as my tool of choice for technical documentation, I would feel happier and more confident using Office products for smaller projects and presentations now.

You can find out more about the book and order it direct from O’Reilly here.

Dealing with Rogue Fonts in FrameMaker

This is a FrameMaker gotcha that occurs frequently. You’ve used a font somewhere in a .fm file, moved the file to another machine, and got an error saying the font’s not available and will be substituted by something else. Sometimes this is a nuisance, sometimes it’s a really big deal.

Temporary Substitution and Permanent Substitution

First things first. Check whether any substitution FrameMaker makes will be permanent or temporary before you do anything with the file. Depending on your settings, once you hit Save, the substitution could be made permanent, and if you don’t have another template to import from, or if the font usage is a manual style override, then you’ve lost the correct style information forever. What’s more, you get no say in which font FrameMaker uses instead, so you might just be creating a new, different problem if you allow a permanent auto-substitution.

To check how FrameMaker is handling missing fonts, select File | Preferences | General…, and in the dialog that appears see whether the check box beside Remember Missing Font Names is selected or not.

If it’s selected, FrameMaker will substitute another font while you’re editing on the current machine, but if you move to a machine with the original font installed, it’ll start using that one again. If the check box isn’t selected, then FrameMaker substitutes another font for the one that’s missing, and when you save, the substitution becomes permanent.

If you want to change the Remember Missing Font Names behaviour, close any open files first (without saving), then:

If you are 100% sure that the font should never appear here under any circumstances, de-select the box. Open your file, FrameMaker will substitute a font you do have; save your file, and the rogue font is gone forever, but you’re stuck with whichever substitution FrameMaker went for.
If you want all the original font information for the file to be remembered, select the check box, and work away, secure in the knowledge that things will look as they should again when you move to a machine with the correct fonts.
If you don’t particularly care eitherways, select the check box anyway – if it’s a shared document someone else might care.

Where’s the Font?

If you want to track down where a missing font is used, FrameMaker’s Find/Change function will help you do so.

Open the Find/Change dialog box/tab/panel/whatever you’re having yourself.
Select Character Format from the Find drop-down list.
Select the font you were warned about in the Family drop-down list at the top of the ensuing dialog box.
To make things easy, unavailable fonts appear greyed out in the Family drop-down list, so you can identify them at a glance. Hooray.
Next, repeat steps 1-3 on Body pages, Master pages and Reference pages separately. Find/change operations only apply to the page type you’re currently on. Le sigh.

If you find the font, you can make a call on whether the usage is valid or not. If it’s not, get rid of it; if it is, keep it. Simples.

Sometimes, though, you won’t find the font on Body, Master or Reference pages. In this case, it’s truly rogue, and the best way to proceed, provided it’s either the only font that you’ve been warned about or you’ve had the same result for all missing fonts reported, is to de-select the Remember Missing Font Names check box and save the file. FrameMaker will eradicate it from the file forever and you can live happily ever after.

Back in Kansas

If you preserved original font information while you edited, then you should either install the missing font on your current machine, or move to a machine with the font installed before you publish.

If you didn’t preserve original font information, you should re-import your paragraph and character formats from a copy of your template before publishing. (And make sure you’re on a machine with the required fonts.)

Aside – Missing Fonts Hinder Global Find/Change

If you’re performing a global find/change across a book, and some files in the book use missing fonts, FrameMaker refuses to open them to search through. The simple work around here is to open all files in the book before starting your search.

Roomba

It was the Cheerios that broke this camel’s back, and after the bazillionth morning in a row of scraping the damn things out of the carpet after getting back from the school run, I decided to succumb to the lure of Roomba’s robot-y goodness. We’d recently discovered that not one but two of our friends had already gone over to the robot side and couldn’t speak highly enough of their pets, so we decided to give it a go.

A bit of online price comparison, and my order was in by lunchtime. I ordered a 555 model – a few of the bells and whistles that might make a difference, but not too fancy. Two days later, Roomba had arrived, and an overnight charge later my life transformed forever.

How Roomba Changed my Life

Roomba can be programmed to run automatically once on each day of the week, or be left to manual kickstart as and when needed. I’ve set ours to run when we’re doing the school run during the week, and left weekends to a push of the button so he doesn’t get in the way of breakfast or play. (Actually, the manual weekend runs are more for his good than ours, since the smallest person in the house loves to follow him round and kick his bumper to make him change direction. This way, we can wait till there’s no one who wants to play around before letting Roomba out to do his thang.)

The joy of the automatic weektime clean is that after rushing around delivering everyone to where they should be for the day, I arrive in to a spick and span living room and office, and can settle straight away to my work without fussing over the state of the place. It might only save minutes of labour each day, but the mental wellbeing and clarity is worth a lot to my productivity.

Everyone has been warned that any toys or papers left on the floor are liable to be eaten by the robot and won’t be coming back (no, it won’t really eat your stuff, but don’t tell my kids that), so everyone joins in a quick 2 minute pickup of “stuff” before Roomba springs into action, and even that daily contribution means that the house is neater and more organised than usual.

Also, since the place is generally clean, small spills/messes seem worth cleaning up, since the tidy patch left behind no longer draws attention to how dirty the rest of the floor is. He even gets underneath the furniture, so no mounds of dust festering and waiting to surprise us the day we relocate the bookcase in 5 years’ time.

Finally, as someone pointed out in a review I read on another site – having the downstairs clean on an ongoing basis means less dirt dragged upstairs on the bottoms of shoes, so upstairs needs less cleaning too.

Every little helps.

But is it Eco?

Our upright cleaner uses ~1200Watts. Before Roomba, I would use this anything from once a day to once a week (depending on how mess-sensitive I was feeling), for anything from 5 to 20 minutes at a time. Let’s take a ball park figure of 45 minutes a week, so 900Wh/wk used.

Roomba runs once daily and keeps going till it’s used up its battery reserves, then it recharges. The charging station uses 30W and the battery charges fully in ~3 hours, so 90Wh, 7 days a week = 630Wh/wk.

That leaves me 270Wh of regular vacuum time per week for top-up cleaning. Though since Roomba’s arrival, the regular vacuum cleaner has been sitting forlornly in a corner being ignored, so I reckon that on balance we’ll be using less electricity annually for our daily clean with occasional top-ups than the sporadic vacuuming we were already doing.

What does a Roomba Cost?

Refurbished series 500 Roombas go on eBay for ~€250, but all seem to come from the US. By the time you’ve added shipping, waited weeks for delivery, potentially paid duty on the lot, and bought an adapter for the plug, it’s tempting to just buy locally and know that it’ll be less hassle to get support if you have a problem. We bought direct from iRobot’s Ireland site who throw in free shipping, which is nice. The 555 cost €370.

Cleaning the Roomba

Of course, it’s not all happy happy joy joy. Roomba needs to be emptied and cleaned too. His bin is small, so the emptying is daily (in our home at least). The silver lining is that this gives you a chance to admire just what a good job he’s doing – he easily picks up as much fine dust and fluff as a Dyson, which I wasn’t expecting – I thought it would get the bigger dirt only. You’ll want to tap the fine dust out of the filter periodically to keep suction levels up, and maybe even give it a gentle wash (there are videos on YouTube). The brush and beater need to be de-haired and de-fluffed at least every other day if you’re running the Roomba on carpet. It comes with a tool to comb stuff out of the bristles, but you might need a tweezers or decent finger nails to get the stuff that wraps itself around the ends. The first time we cleaned the brushes, hubby and I both took turns picking bits out of different parts of the brush and beater over about an hour, but every time we popped them back in Roomba would complain they needed cleaning again immediately. Eventually, Dave figured out that hair had snagged behind the bearings, so popped them off and cleaned in the crevices, and everything was dandy again. Since that first day, we’ve got the knack and now it takes ~2 minutes to clean both brush and beater thoroughly.

Take Home Message

The Roomba’s a good little guy to have around. He won’t do all the work, but his presence encourages me to spend 5 minutes a day doing my bit to facilitate him doing his bit, and the overall result is greater than the sum of its parts.

Finally, I’ll leave you with an earworm: Roomba mm mm Roomba doobie doo doo Roomba oo oo ye-e-eah… to the tune of M-bop by Hansen. Enjoy the rest of your day! 😉

Sugru!

Sugru is great stuff. It’s like plasticine for grownups, but with a noble purpose.

It comes measured out into small portions of colourful squishiness in foil sachets. It’s very soft and malleable when fresh out of the pack, so you can mould it to just about any shape, but it dries completely hard when exposed to air, which means it’s extremely durable once in the required form. I found it a little too soft and sticky when I first took it out of the pack, so you might want to take it out and leave it sit for a few minutes before you start working with it.

I must admit, I was predisposed to like this stuff before I even got my hands on it. I picked up a similar product in a hardware shop more than a decade ago, and it was a favourite for a while, till disaster struck. (Google suggests it might be one of the products mentioned on this Wikipedia page.) This product came as hard plastic pellets that melted in hot water, then became rigid again once cooled. I used it for a number of small repairs, and to cover sharp corners and edges on various items (for example a bolt under my bike saddle that regularly snagged skirts and coats). All was well till I replaced a missing zip toggle on a coat, forgot about the melting in hot water issue, and put it through a hot wash with disastrous consequences. I slightly went off it after that.

But back to lovely, lovely Sugru, with none of the melty issues.

My first repair with it was to the lid of a bin we keep in the garden. Probably due to weather exposure, the frame of the lid is prone to cracking, and we’d already replaced it once, but when the new lid cracked a few months ago, I was able to join it back together (somewhat inelegantly) with a nice big wodge of Sugru.

It was very satisfying not to have to buy a whole entire new plastic bin and lid for the sake of one small, though critical, crack. It’ll be interesting to see how the Sugru join copes with the weather extremes this winter, but it’s been happy enough out there for the last 6 months or so.

Dave has also used Sugru to cap the decorative “spikes” on our fire guard, to avoid accidental eye-poking-out, although the kids were less interested in going anywhere near them till they went all colourful and interesting, so I question the success of that project.

One of the niftiest repairs I’ve heard of is wrapping Sugru around a screw that’s missing its nut, waiting for it to set, then unscrewing it and hey presto, you have a new nut that’s a perfect match to the tread of the screw. How clever is that?

http://en.wikipedia.org/wiki/Polycaprolactone

I Like Big Butts

With talk of water charges coming in next year, now is the time to be investigating options for reducing water usage, and harvesting rainwater and grey water. We’ve not figured out an ideal solution for the grey water yet (all our water-using appliances are at ground level, so we can’t divert to anywhere gravity can help us reuse the water), and the small people are cancelling out most of our water usage reduction measures, but when it comes to rainwater harvesting, we have a nice solution that’s working well.

A few years back, I picked up a 100L water butt and a diverter kit, and we hooked it up to the main downpipe at the back of the house. One decent rainfall had it filled, showers kept it topped up, and for about 2 years thereafter we didn’t have to take water from the kitchen tap once to water any plant inside or outside the house. Then we had a bit of a drought, so the veggies got tap water and the flowers were left to wilt. Given how well we’d gotten on with butt number 1, we decided to put a gutter and downpipe on the shed and to collect runoff from that roof too, so a second butt was installed. After a decent rainfall, both are full to the brim, and we can keep the garden lush for a couple of weeks of drought at least before we need to consider resorting to the inside tap.

I bought all the parts for the first setup separately, so it cost a fair amount, but by the time we were setting up the second butt, Argos were doing a complete kit for a much lower price, and at the time of writing, it’s on sale at a lower price again, so if you’re considering getting a butt of your own, go grab one quick!

I’m particularly impressed by the diverter component of the system. It’s a nifty little bit of engineering.

To install it, you slice your downpipe in two horizontally, then stick the diverter between the two halves. A ring-shaped “moat” sits between the two halves of the downpipe, with an outlet that can be connected to a short hose to join the diverter to a water butt. The outside wall of the moat is taller than the inside wall, so when it fills, it overflows back down the inside of the drainpipe.

Without a diverter (1), rain just gets washed straight down the downpipe and into the drain.
With a diverter connected to an empty water butt (2), rain pools in the moat and flows off into the connected butt.
When the butt is full (3), collected rain can’t exit via the diverter hose anymore, so pools till it overflows the moat on the inside of the downpipe and flows to the drain as usual.

For a relatively small investment, you’re set up with a reservoir that should amply water a small garden year round, and provide untreated water suitable for jobs such as scrubbing down a patio, and rinsing dirty wellies and garden tools. For larger gardens, you can source larger butts from garden centres and specialist suppliers, or do what we do and dot a few different smaller butts around the garden so that you have a ready water supply in multiple locations.