jazzfish: Windows error message "Error 255: Too many errors." (Too many errors)
[personal profile] jazzfish
At $work.previous we wrote documentation using Robohelp, a piece of tech writing software that's been around in some form or another since the late nineties and has been owned by Adobe since the mid-2000s. Robohelp is clunky and awful but it works and I'm more or less used to its shenanigans.

Shortly before I got laid off we started considering migrating to a program called Flare. Flare was developed by some ex-Robohelp folks who didn't want to work for Adobe and quit to make a version of Robohelp that didn't suck. They were ... not entirely successful. About the best that can be said about it is that it sucks differently than Robohelp.

As you might guess, documentation at $work.current works off of Flare. It uses the same general structure as Robohelp: a given documentation project consists of a whole bunch of HTML (really XML) topic files, tied together with various project files, and styled through CSS. The content can be compiled into a number of output formats, including PDF, Word, compiled Help (CHM), and something called "Webhelp" that's a bunch of HTML files styled in CSS and tied together with a bunch of Javascript.

Currently we only deliver PDFs, but management has been making noises at least since I've been there about wanting online HTML documentation. I said "sure, there's a setting for that, shouldn't be too bad, probably just have to tweak the skin and the style sheet." Trouble is, ex-coworker Bill was the one who handled all the CSS nonsense for Robohelp at $job.previous. I'd forgotten, or blocked out, all the headaches it put him through. Or maybe I just hoped Flare would be better. (Cue hollow laughter.)

I spent a couple of formative years as a software tester in opposition to several different kinds of unpleasant programmer. This gave me Strong Opinions about usability and user experience. Also, [personal profile] jadelennox is a vocal advocate for accessibility in software/website design and some of that has rubbed off on me. So I have a particular personal interest in making the design Not Suck, where "sucking" could be defined as either "is difficult to use" or "reacts badly to nonstandard user choices."

CSS... okay, a brief primer. HTML is a markup language. The point of HTML is to say "this text is a heading, and this is a paragraph, and this is a smaller heading, and this is a list of things" etc. These days the web relies on Cascading Style Sheet (CSS) files to tell it what to make those various markups look like. So you have an entry in your CSS file that says "make the biggest headings be huge and fancy-font, and the second headings be smaller and bright blue, and indent the lists by a couple of tabs," that sort of thing.

(You can also use CSS to make your webpage sit up, roll over, and beg, but that is outside the scope of the current discussion. And if you try it without knowing what you're doing you are more likely going to get a webpage that just plays dead.)

There are (at least) four different ways to specify units of measurement in CSS.:
  • You can use point size (pt), which is the same thing you use to set the size of your fonts in Word. This works really well in print and kind of questionably everywhere else.
  • You can use pixel size (px). This seems like it ought to work fine on a screen, and it sort of does: it runs into trouble on phones, but what doesn't. The real problem with px is that they don't scale: if the user has said "I want my fonts to show in large size because that way I can read them" and you're telling everything to show up at 16px, the user isn't going to be able to read your site because you were a jerk who thought you knew better than they did.
  • You can use relative measurements, of which there are two that I know of: percent, which is basically "in percentages of the size of the last thing," and ems, which in a horrific abuse of a term from the print industry are "the height of the default line of text." These are trickier to work with but much more rewarding.
The main trouble with Flare's stylesheet is that it uses point size except where it uses pixel size.

I spent much of last Thursday and Friday learning enough CSS to be able to write the above, and then going through the stylesheet manually, replacing absolute measurements with relative ones, checking to see how terrible it looked, and tweaking.

At about four-thirty on Friday afternoon, Flare's magic hypercustomisable numbered-lists, which we use for writing step-by-step procedures because software instructions tend to have lots of options and warnings and things that interrupt the basic flow of the numbered list, started breaking spectacularly when I tried to adjust their formatting. I poked around in the stylesheet and in the Webhelp skin and didn't see anything. I finally checked in the Webhelp HTML source, where I discovered that the magic numbered-lists are styled in the Webhelp output by means of an invisible table, where the numbers are in one column and the content is in an adjacent column.

At which point I threw up my hands in despair and went home. I haven't had the fortitude to try again this week.
Identity URL: 
Account name:
If you don't have an account you can create one now.
HTML doesn't work in the subject.


Notice: This account is set to log the IP addresses of people who comment anonymously.
Links will be displayed as unclickable URLs to help prevent spam.


jazzfish: Jazz Fish: beret, sunglasses, saxophone (Default)
Tucker McKinnon

Most Popular Tags

Adventures in Mamboland

"Jazz Fish, a saxophone playing wanderer, finds himself in Mamboland at a critical phase in his life." --Howie Green, on his book Jazz Fish Zen

Yeah. That sounds about right.

Expand Cut Tags

No cut tags