A fellow alumna of my programming bootcamp DM’d me on Slack today to this effect:

Hey, sorry to bother you, but I had a question, saw you were online, and highly value your opinion. I just got my first referral (yay!), but I don’t know if I should send a cover letter with my résumé. I’ve gotten mixed answers.

Aw, gee, shucks. I am ever ready to give an unsolicited opinion, as friends and foes alike would probably attest, but it’s nice to be asked!

My response

In general, one should always include some kind of covering note. Even if I’m sending my résumé to someone so they can pass it over the transom, I include a version of what I would put in a cover letter,

• highlighting how the job matches my experience and interests,
• pointing out anything relevant that might not be obvious from looking at my résumé, and
• touching on why I’m interested in working at that company.

Then if that person wants to, they can either forward the whole e-mail or cut and paste, per their discretion. The goal is to make it easy for them to refer you.

And if you’re applying through an online form but then adding a referrer’s name, you should still include a cover letter, because you never know whose hands your application will actually end up in.

Pro tip: Use your imagination

Composing a cover letter as if you’re sending it to someone whom you know, for them to forward on, is a good way to avoid the zombielike tone that tends to make such letters awful both to write and to read.

Imagine someone who likes you, someone who wants you to succeed, someone who cares, and give them the information they need to pitch you to their boss.

Because that’s essentially what’s happening. Everyone wants to be the person who finds the person who gets hired—even when there’s no referral bonus involved. They want to be able to fill that position. So they’ll be excited if they see a note that lets them believe that you might be that person.

Applying for jobs can make you feel worthless and like everybody’s slamming doors in your face all day, but in reality it’s not all antagonistic, behind those closed doors.

Even if you don’t know for sure who’s going to be reading your cover letter (and you did at least try to research this using teh Google, didn’t you?), it helps to imagine that you know them, so you can strike an appropriate tone of warmth, respect, and poise.

[Intellectual property theft alert: I expressed similar sentiments when I first discovered this correlation between readable cover letters and relative familiarity with the recipient, nearly a decade ago. If you wish to read that crankier batch of advice, which was issued from the perspective of a hiring manager who had no HR department to screen candidates, see the post Job application tips on my non-Medium (Maximum?) blog.]

Today at school we got an hourlong presentation on using LinkedIn effectively, which ended with a summary slide of statements we were to evaluate as true or false. One of these was “You should add soft skills to your skills,” and the “correct” answer seemed to be, more or less, false. My hand shot up, and I said that well, actually, soft skills are extremely important in tech, as they are everywhere, and that if you’re an excellent programmer who can’t communicate with other people, nobody with any sense is going to want you on their team.

Later, I elaborated via Slack to one of the school administrators as follows:

…one of the few advantages that bootcamp graduates have over recent CS graduates is that they do, on average, tend to have more real-life experience working on teams, managing, being managed, and working with other humans in general. And chronic undervaluing of soft skills is specifically part of why the tech industry is a notorious trash fire, not just for women and people of color, but for everyone (encouragement of burnout, lousy work/life balance, etc.). So to have a career services person tell the entire student body to deemphasize soft skills in our LinkedIn profiles and similar places seems counterproductive.

This is literally why we can’t have nice things.

A more helpful approach would be to explain how to use this experience to one’s advantage, in statements of interest, cover letters, and interviews.

Several hours later, I’m still mildly exercised about this. So I sifted through my bookmarks for a couple of favorite discussions of the communication issue, to share with my classmates. It ended up being too much to dump into Slack, and we’re supposed to be blogging regularly about tech-related things, because personal branding, so I’m throwing them here.

This post is so totally on brand for me.

1. Andrea Goulet: “Communication Is Just As Important As Code”

• Video: https://vimeo.com/177846366
• Slides + approximate transcript: http://corgibytes.com/blog/2016/06/06/communication-and-code/

Excerpt:

…getting better at your communication is the best way to level up your career.

If you want be a Lead Dev, a CTO, or own your own business, communicating effectively with people who don’t code every day is a big part of your job.

If you want people to contribute to your open source project, communication is what makes them feel welcome and keeps them around.

And if you want other people to use your ideas, you need to learn how to blog, speak, and maybe even write books. All of that is communication.

☚ Sidebar: “Soft skills” as feminine, and therefore utterly worthless, duh

The cultural tendency to identify soft skills with “women’s work,” which is obviously not worth paying real cash money for, is a whole other infuriating aspect of this topic, which I could spend all night posting links about, assuming I didn’t suffer a rage-blackout within the first half-hour. Instead, I will just mention this oldie but goodie: Lauren Bacon: “Women in Tech and Empathy Work.”

2. Sam Phippen: “On the unreasonable reality of ‘junior’ developer interviews”

https://medium.com/@samphippen/on-the-unreasonable-reality-of-junior-developer-interviews-946498c0ad57

Excerpt:

Communication is the most important thing we do as developers. All computer problems are people problems. [boldface in the original, but I would double-bold it if I could]

☚ Sidebar: !@#$% whiteboarding

If you’ve heard me rant about whiteboarding tests, the literally impossible one described in Sam’s post is the kind of thing that sets me off. Yes, whiteboarding is a worthwhile exercise for us as students. Whiteboarding forces you to think through a problem differently, when you can’t rely on autocomplete or test your ideas as you go along. But a lot of places that use whiteboarding tests are just trying to cover up for not having any idea of (a) what jobs they’re actually hiring for, and (b) how to actually identify the right people for those jobs. I have so many other great links about how whiteboarding is trash as an interviewing technique; don’t get me started.

Well, more started.

3. Sarah Mei’s Twitter thread on coding bootcamp grads versus CS grads

https://twitter.com/i/web/status/881958594094268416

Excerpt:

Code school grads…often already have communication skills from a previous career. They just need to adapt them to tech.

Because of these existing skills, while code school grads stay junior longer, they accelerate dramatically past their CS peers at mid-level.

Anything technical can be spot-learned with google & wikipedia; communication skills are harder to teach, & seem to take longer to learn.

With most people, when I 🖤 their tweets, what I really mean is ★, but with Sarah Mei, I actually mean 🖤. She is so fab.

</rant>

So, yeah, maybe you don’t want to list your so-called soft skills at the tippy top of a tech CV, but they are by no means unimportant, and over the long run, they may give you an advantage over developers who have had more formal training.

Nice dress, Julie.

Tomorrow is my first day in the immersive curriculum of the Grace Hopper Academy full-stack JavaScript “bootcamp,” (as opposed to the part-time, remote portion, which has been going on since April), and we’ve been asked to write a blog post introducing ourselves to our classmates and anyone else who happens to stumble in.

(Note: I already have a bunch of rusty old blogs, most notably India, Ink., which is mostly about my work in and around book publishing, and ITPindia, which is a classwork blog from my ill-fated 2008–2010 stint in grad school. There’s also DrawMo!, a group blog I created to manage a daily drawing challenge that happened a couple of years in a row.)

The questions we’ve been asked to answer in our first post are as follows:

Why are you attending Fullstack Academy?

There are two forks to this question: Why are you attending a programming bootcamp? and Why are you attending this one? I’m something of a completionist, so I’ll address both.

a

One of the things I most wanted to learn when I applied to my graduate program was computer programming, and that was certainly what all the most fun stuff I did there was about. Back when I attended, though, ITP was teaching the version of Processing that was based on Java, and between hating Java and hating ITP, by the time I left there, I pretty much never wanted to see that language again; accordingly, I can no longer really understand any of the code I posted on my old classwork blog. Being able to rewrite that stuff in JS is an eventual goal.

I didn’t touch programming again for several years. In the meantime, though, all these bootcamps had started popping up. Flatiron School was the first one I heard about, and I thought it sounded really interesting, but even if I had been convinced of its quality and efficacy back then, I was so completely beyond broke from the combined financial devastation of attending grad school full-time for two years plus the concurrent recession that there was no way I could even think about trying it.

I ended up going back to working in book publishing, which I’d been doing for most of the previous decade, because that’s where most of my connections and experience were. The big difference was that the Kindle and iPad had blown up while I was in school, so I returned as an e-book developer rather than as a book designer or production manager. I didn’t know much about it, but neither did anybody else. We made it up as we went along, much as we’d done on websites a decade earlier.

Then in 2015, I got hired to handle the e-book library at Amplify, an educational technology company, and I had my first experience working with modern software teams. I’d collaborated with individual programmers before, and with a couple of small firms, but never at a place that had multiple groups working on different chunks of a big product. I liked learning how such projects were managed, and getting to participate in structured QA and problem-solving. Jira tickets! Whee!

I talked with some of my colleagues on the content production team about starting up a JavaScript study group, as I’d been meaning to learn how to use that for a long time, and it seemed like time. It turned out more of them wanted to solidify their HTML and CSS skills, so I started compiling notes on how to help with that. And then…

We all got laid off. And so it goes.

I knew I didn’t want to go back into publishing, but my coding skillset was too narrow and weird (ask me about HTML and CSS support in e-readers!) for me to get hired at another tech company.

What a perfect time to sign up for a coding bootcamp!

I started attending more tech meetups, and listening to the super-excellent CodeNewbie podcast, and I tried out Free Code Camp, and I started learning JavaScript on my own. It was around that time that I heard about the Grace Hopper Academy, which had just started up, and I thought it sounded awesome.

But I was also kiiiiind of looking for work, as one does when one has no income, when a six-month temp job on a small, agile Web team fell in my way. I thought it’d be a great place to park myself while I learned a bit more about the agile development process, continued studying JS, and prepared to apply to an immersive program. I thought the six-month contract would be ideal, as then I’d have a deadline for getting my shit together.

More than thirteen months later—this past Friday—I finally said goodbye to my lovely colleagues at MoMA.org, and here we are. So much for deadlines.

this

The key things that attracted me to the Grace Hopper Academy were as follows:

All-women cohort.

I didn’t understand the appeal of all-women schools when I was applying to undergrad programs, but in my tech-oriented graduate program the idea started to appeal, as there was definitely some gendered bullshit going on. It’s hard enough learning to program/upending your entire life without having those kinds of interactions, y’know? I’d just rather not waste bandwidth on that when I can avoid it, thanks.

Meanwhile, I’ve had consistently fantastic experiences with women-in-tech groups and events, such as Write/Speak/Code, so when this program started up, it immediately became my top choice.

Some coverage of actual computer science.

I don’t do well with magical incantations. If I’m going to do something, I tend to do it better if I have some idea of what’s actually going on. One of the things I found most frustrating about learning Processing is how it attempted to hide the gnarly Java stuff behind a (relatively) friendly library and IDE. This meant that if you wanted to do anything not graphics-focused, you basically had to learn Java all over again, from scratch.

I was an English major in college; I’m much more interested in crunching text than in making bouncy graphics. I managed to stumble through Allison Parrish’s Programming A to Z class in Java, but I’m pretty sure it was harder for me to learn that coming from friendly, cuddly Processing than it would have been had we started with some thorny abstractions. And as I’ve mentioned, I retained almost none of what I “learned,” in the long term. So, bring on the thorns, please.

It takes time and effort to learn the whys as well as the hows, but I am convinced that over time, this will make it easier and faster to become good at what I do.

JavaScript-based curriculum.

I have learned a little bit of a lot of programming languages over the last twenty years, so I waffled intensely over the question of which one language to properly learn first. But ultimately it comes down to this: a lot of people sniff at JavaScript—I heard the standard string of complaints just the other day, from one of the supernice developers at MoMA—but if you’re going to do stuff on the Web, you have to know your way around JavaScript. So I might as well start there.

Back-loaded tuition.

I’ve worked at nonprofits and in book publishing for most of my so-called career; I don’t happen to have ten to twenty grand stuffed in my mattress. (For anyone who’s wondering: nonprofits tend to pay better.) What I do have is student loans that I might be paying off until I die. There are certainly other ways to work around this problem, but not paying tuition until you actually have a job is one of the most practicable ones I’ve found.

Solid support for career change and advancement.

I’ve already successfully shifted careers a couple of times, and I think I’ve done reasonably well at getting hired and getting promoted, but I’ll still take all the help I can get.

Is this a career change? If so, why?

Yes, and no.

I started learning Web development in 1996, pretty much the same time I first saw the Web itself. (Yes, I’m old enough that I still capitalize things like “Web.”) I was the webmaster of Poets.org, back when that was a job title serious people had; it ran on MS IIS, MS SQL Server, ColdFusion, and some other closed-source stuff, and though I didn’t build it, I did handle the day-to-day maintenance, both back- and front-end. When I started hearing about the open-source software movement, I played around with rebuilding the site on the LAMP stack, but it was too many things for me to learn all at once from O’Reilly books, while on the job. Still, I wanted to.

Then September 11 happened, and I got laid off, and book publishing looked fun, so I went and did that for several years. I still approached things like a coder, though, and used a proper text editor, even when the coding was just cleaning up Quark XPress Tags or messing with WordPress templates. And because I had started learning typesetting and CSS around the same time, and I’d been having to do conversion of text from one format to another at every job, I was always thinking about (a) the separation of presentation from content, (b) how to refactor things, and (c) how to automate processes.

The next time I worked on a website was for an online magazine, and though my title was, somewhat ridiculously, “art director,” I found it easier to communicate with our developer by sending code snippets than by making mockups or describing what I wanted.

When I became a full time e-book developer, I spent literally all day in HTML, CSS, and XML files. I have Feelings about coding standards, CSS hygiene, version control, and documentation.

When I worked at Amplify, two teams’ standups happened literally right behind my chair, so I got a big dose of agile software development practices, whether I needed it or not.

And this is kind of what my last month at MoMA looked like:

Have I ever been what is generally meant by the term software developer? Absolutely not. But I feel like I have a bunch of the pieces; they just don’t fit together yet.

What is your work history?

I’ve rambled too much about this already, but the gist is:

• nonprofit arts administrator
• webmaster at a nonprofit arts organization
• production editor/managing editor (with bonus typesetting and design)
• typesetter and book designer
• book designer
• art director at a nonprofit arts organization, mostly for the daily online magazine
• e-book developer and QA person
• managing editor again (but! including editing, designing, and typesetting, as well as producing e-books)
• e-book developer again, but at a software company, with some ad-hoc product management thrown in
• digital media producer for a nonprofit arts organization

What motivated you to learn to code?

I’ve always been more of a craftsperson than anything else, and for many years my life has revolved around things that are crafted out of code, so it makes sense to learn how to build those things myself.

Tra la.

Well, shifting my Adobe Creative Cloud subscription to annual and putting it on the card took care of more than half the challenge. :/

And then I replaced my inkjet printer, which—like every other inkjet I’ve ever owned—had died of infrequent use.

As anyone who’s owned an inkjet knows, if you don’t use it often enough, the heads dry up. Then you end up having to run the head-cleaning utility all the time, which wastes a lot of ink, and you have to replace the ink cartridges all the time, which wastes a lot more. And since printer ink is one of the most expensive liquids on the planet, wasting it is baaaaad. Besides which, eventually those underused nozzles get permanently gummed up, and the machine stops working altogether.

My last printer, a Canon PIXMA MX870, had an okay run, limping along from March 2010 until mid-2016. But for the last year of its life, it was basically a monochrome device—with its one color not necessarily being black—and finally it started displaying an error message upon startup and refused to print anything at all.

So, Amperbang LLC replaced it with Wirecutter’s recommended (or, more accurately, least loathed) all-in-one color printer, which is the HP OfficeJet Pro 8720, and yesterday, as soon as I was done setting up this appliance, I started researching how to automate having it print a test page every few days, to keep the heads clean. It turns out this is not difficult to do, but in case you—or Future Me—want to do something similar, I’ll try to make the process even easier by summarizing what I’ve learned.

Prerequisites

• You’re on a Mac. I did this on a late-2013 MacBook Pro running Sierra (10.12.2).
• You have a wifi-enabled or otherwise always connected printer, which either is always on or can be scheduled to power up (and down) at regular intervals.

1. Schedule the printer to turn on and off at certain times each day.

Totally optional. If you don’t want to bother with this or if your printer doesn’t have this feature, you can either leave it on all the time, or let the print job sit in your Mac’s queue until the next time you turn the printer on.

On the HP OfficeJet 8720, this vaguely documented process goes as follows:

a. On the printer control panel, swipe down from the top of the screen to open the Dashboard.

b. Scroll the menu bar all the way to the right, and tap the icon that looks like two leaves.

This is not the correct screen; do not be fooled:

c. Once you find the Environmental Settings screen, tap “Schedule On/Off.”

d. Follow the prompts to set the days and times at which you want the printer to turn off and on.

Setting the days of the week:

Since I wanted to schedule my printer tests by day of the month rather than day of the week (which would be a lot easier), I set the printer to turn on and off every day. (And then I undid it, on which more later.)

Setting the time of day:

At 7:00 a.m., I am still in bed, but the cats are probably awake, so the printer’s powering up and down might enrich their boring lives.

Confirming your settings:

“Every everyday,” forsooth.

You’ll need to set both on and off days and times, and to activate the schedule.

2. Set up your Mac to turn on and off at the same times as the printer.

Optional. Per step 4 below, this is required if using cron, optional if you’re using launchd. You’re not required to use cron, though, so overall, it’s optional.

You can set this up using the Energy Saver preference pane.

The timing options are not very granular, which is partly why I decided to ditch this method. If I wanted to run this task only once a week, these options would be fine. For a twice-weekly task, though, you end up having to set the schedule for every day.

3. Create an Automator app that prints a document.

Required.

I accomplished this using the instructions in this post by Clay Harmon:
Exercising Your Printer With Automator And Crontab.

I set up my app to print this exciting PDF—
http://cream.sourceforge.net/ColorCard.pdf
—but a Google image search for inkjet printer test page will turn up lots of other options. You might want one that uses less ink, for instance.

Here are the Automator settings. I saved it to ~/Applications1 as PrintTestPage.app:

4. Schedule your app to run.

Required. But there are (at least) two ways to do this, and you can choose either one, depending on your desired schedule and how completely automated you want this chore to be.

a. Cron

Cron, as in c[h]ronological, is a venerable Unix utility that performs tasks on a schedule. It can perform those tasks only if your computer is awake; otherwise, nothing happens. But if your computer is always awake—e.g., if you’re running the test-page-printing app from a server—or if you don’t mind scheduling for it to wake and sleep at predetermined times, per step 2 above, it’s rat simple.

To create a cron job to run your test-page-printing app, follow Clay Harmon’s step-by-step instructions.

Here’s the command I set up:

(The top 9 lines are just to show you what each part of the command does; they’re cribbed from Calomel.org’s Cron and At post.)

This job will run my Automator app at 7:30 a.m. on the 1st, 5th, 10th, 15th, 20th, and 25th day of each month, as long as my laptop is awake at that hour.

But then I thought that maybe I don’t want the printer and laptop turning on every day from 7 to 8 a.m., when I’m only going to print a test page every fifth day. Maybe I just want the job to run at approximately the same time on every fifth day, at whatever time I actually wake my laptop—which is nearly always going to be after 8 a.m. So…

b. Launchd

If you just want the task to happen eventually, whether your computer is awake at the prescribed time or not, a better solution—and the method Apple prefers over cron—is to use the launchd framework, which was introduced with Mac OS X Tiger.

If a launchd agent is scheduled to start while your Mac is asleep, it just waits until the next time the computer is awake. And the task will run only once, even if more than one scheduled occurrence passed by while the computer was off or sleeping—so you won’t end up with a stack of test pages printing all in a row, if your computer’s been shut down for a month. (During which time your inkjet printer has diiiiiied…)

Setting up a launchd agent is slightly more complex than creating a cron job, but since this method lets you skip step 2 above, it’s probably a wash, effortwise.

There are apps that can help you create the necessary .plist file, such as Lingon X ($10) and LaunchControl ($10). The makers of LaunchControl also host the site launchd.info, which explains how to create and use artisanal launchd property lists, interlarded with pitches for letting their software handle everything for you.

If like me you don’t anticipate creating another launchd agent any time soon, and you aren’t $10 worth of lazy, you can probably just dive into the XML yourself. Here’s the file I created:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/opt/X11/bin:/bin/bash:/usr/local/sbin</string>
  </dict>
  <key>Label</key>
  <string>com.amperbang.printTestPage</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Applications/PrintTestPage.app/Contents/MacOS/Application Stub</string>
  </array>
  <key>RunAtLoad</key>
  <false/>
  <key>StartCalendarInterval</key>
  <array>
    <dict>
      <key>Day</key>
      <integer>1</integer>
      <key>Hour</key>
      <integer>7</integer>
      <key>Minute</key>
      <integer>30</integer>
    </dict>
    <dict>
      <key>Day</key>
      <integer>5</integer>
      <key>Hour</key>
      <integer>7</integer>
      <key>Minute</key>
      <integer>30</integer>
    </dict>
    <dict>
      <key>Day</key>
      <integer>10</integer>
      <key>Hour</key>
      <integer>7</integer>
      <key>Minute</key>
      <integer>30</integer>
    </dict>
    <dict>
      <key>Day</key>
      <integer>15</integer>
      <key>Hour</key>
      <integer>7</integer>
      <key>Minute</key>
      <integer>30</integer>
    </dict>
    <dict>
      <key>Day</key>
      <integer>20</integer>
      <key>Hour</key>
      <integer>7</integer>
      <key>Minute</key>
      <integer>30</integer>
    </dict>
    <dict>
      <key>Day</key>
      <integer>25</integer>
      <key>Hour</key>
      <integer>7</integer>
      <key>Minute</key>
      <integer>30</integer>
    </dict>
  </array>
</dict>
</plist>

This agent hopes to run my Automator app at 7:30 a.m. on the 1st, 5th, 10th, 15th, 20th, and 25th day of each month. If it can’t run it at 7:30—which it probably never will, because both I and my laptop are dead to the world at that hour—it does so when the laptop wakes, instead. If the printer doesn’t happen to also be awake at that time, the print queue app will squawk at me, which will remind me to turn the printer on.

I placed the .plist file in ~/Library/LaunchAgents/, and I ran the following terminal command to get it loaded the first time:

launchctl load ~/Library/LaunchAgents/com.amperbang.printTestPage.plist

That’s a one-time command, because I had just created this agent. From now on, as I understand matters, the agent should get loaded automatically every time I log in.

If I needed to unload the agent—for example, if I made a change to it and needed to restart it, I’d run

launchctl unload ~/Library/LaunchAgents/com.amperbang.printTestPage.plist

To actually use the agent a single time, off the schedule, I can run the terminal command

launchctl start com.amperbang.printTestPage

When I did this, the test page printed. Woo!

Conclusion

So, after all that research, I’ve ended up using just the Automator app and the launchd agent. No automatic waking and sleeping of printer and computer. It’ll just run when it runs.

Tune in five years from now to find out whether the printer’s still firing on all cylinders…

1. I hate when instructions assume you know things, so let me explicitly say that whenever you see a path beginning with ~/ in Mac-related instructions, this means the address is relative to your user folder. So, if my Mac login name is amperbang, ~/Applications would be in Macintosh HD > Users > amperbang > Applications.

Installation

Installation was a bit of a headache, though the “Getting Started” instructions for video-transcriber were mostly pretty thorough:

• Register for an IBM Bluemix Account.
• Install Node.js and FFMpeg, using Homebrew, which I already had installed for something else.
• “Install Node.js dependences in the usual way,” an instruction which incensed me. I think I figured out what “the usual way” was via StackOverflow, but I now see that Dave MacFarland of Treehouse has written a nicely detailed tutorial: How to Install Node.js and NPM on a Mac.

Here are the Terminal commands that I used during installation (not including installing Homebrew):

$ brew install node ffmpeg
$ cd /Applications/video-transcriber-master
$ npm install

Transcribing

Here is the command (all on one line) that I use every time I need to start the transcription server:

$ WATSON_SPEECH_TO_TEXT_API_USERNAME="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" WATSON_SPEECH_TO_TEXT_API_PASSWORD="xxxxxxxxxxxx" npm start

The software turned out to have a bug in it—or maybe I installed it wrong?—that causes it to crash after it processes more than about 18 minutes of audio. But once I chopped my MP3s into <18-minute chunks, it worked okay, and it’s kind of fun to watch.

I recorded a short video so you can see/hear the app in action. Note that it starts transcribing before the audio starts (around 0:38), runs a bit faster than the sound, and adjusts its transcription as new words are added.

A 16-minute clip takes about 8 minutes to transcribe.

Editing

You can’t edit the text while the transcription is occurring. When it finishes, however, the tool switches into editing mode.

All the words it decided were suspect are highlighted in yellow, and you can click into the text to edit it. Most of the time when you click, the audio will start playing from around that location, so you can verify what was actually said.

Once you’re done editing, you can click “Transcript reviewed,” which does…nothing. Except prevent you from editing the transcript any further? There’s no way to re-enter editing mode.

You can then select your transcribed text, copy, and paste into a real text editor. The timestamps do not get included on your clipboard, alas; one of the three issues filed on GitHub as of this writing is a request for an option to export with the timestamps.

This app is very MVP, and rather fragile. It crashed on clips longer than 18 minutes, and sometimes it just dies for no apparent reason, and you have to restart it from Terminal and refresh the page. If this happens, your previously transcribed text is not saved, so I quickly got into the habit of copying chunks of transcript out early and often, while I worked on it.

Results

Basically, it works, and it’s less tedious than typing it all out by hand, or starting and stopping some more typical MP3 player a million times while you make corrections.

The two Code Newbie transcripts I’ve created so far are on GitHub: https://github.com/indiamos/codenewbie-transcripts. Each one took me perhaps twice as long to edit as the actual running time of the audio, but I expect to get faster at it.

So, let’s say you have an NCX to which you need to add another navpoint, or from which you need to remove one. If the navMap has only four or five points, as in the screenshot below, renumbering by hand is no big deal.

If you’re looking at a book with, say, twenty points, or two hundred, though, forget it. How can we of the scriptless masses automate this vile task? Well, I’ve got it down to about half a minute.

1. With your NCX open, select Text > Remove Line Breaks.
   
2. Under the window’s Text Options menu, turn off Soft Wrap Text, if it’s on. This makes it easier to see what you’re doing.
   
3. Replace all <navPoint with \r<navPoint
   
   Now each navpoint is on its own line.
   
4. Select all lines except the first one, and click Text > Add/Remove Line Numbers…
   
   Fill out the dialog as shown and click “Number.” Now you have sequential numbers at the start of each line.
   
   Hmm . . . See where this is going?
5. Use a RegEx pattern to replace the playOrder values with the numbers you’ve just added. Depending on the source, some NCXs will use different patterns, but this is the pattern I have saved in my Find dialog:
   
   Replace all.
6. Viola! Your points are now renumbered.
   
   You can either leave the list flat or reflow the XML to nest it again. If you’re using BBEdit 11, you may want to install Keith Bolland’s Reflow XML script and assign a shortcut to it; in pre-11 versions, Markup > Tidy > Reflow Document… will do it.
   

Go forth and use your powers for good.

Almost two years ago, I wrote a post called “Degristling the sausage” to explain my method of using BBEdit to get a list of which CSS classes are actually applied in a given EPUB file, out of the sometimes hundreds that are included in the stylesheet. Apparently I’m not the only person who needs to do this sort of thing, because that post has stayed in the top four pages on this site ever since, and clever people keep linking to it.

But BareBones recently released BBEdit 11, and although I’m usually a lateish adopter on software updates—particularly when they remove features I’ve been using for years, such as HTML Tidy (I now use Balthisar Tidy to make my HTML readable)—this time I waited a mere three months before buying the new version, and I immediately wished I’d done so earlier. Because why? Because among many other nice new features,

There’s a new button in the Find and Multi-File Search windows: “Extract”. This button (backed by a command on the Search menu, so you can assign a keyboard equivalent to it) will locate all occurrences of the search string (across multiple files, if appropriate) and those occurrences will be collected into a new untitled text document, separated by line breaks.

I had already meant to post an update to the 2012 post, as I’ve made the process a bit more efficient over the years, but this Extract button radically simplifies things. The new process is as follows:

1. Unzip the EPUB file. (You can edit zipped EPUBs in BBedit, but you won’t get an accurate preview if the pages link to an external CSS file; also, it’s easier to overwrite changes and lose your work if you’re juggling multiple search results windows, as I usually am. So I work on a zipped file only if I’m making very minor changes.) I keep P. Durrant’s ePub Zip/Unzip app in my Finder toolbar so I can drag and drop.

2. Drag the whole folder onto the BBEdit application to open it as a project.

3. Open the Multi-File Search dialog (shift-command-F) and in the “Find:” box put
   class=".*?"

4. Select your project in the “Search in:” box,
   
   make sure “Search nested folders” under “Options…” is checked,
   
   and click “Extract.”Poof! This creates a new document containing just the class attributes—probably several thousand lines long.
   

5. Using the regular Find dialog, replace
   class="(.*?)"\r
   with
   \1\r
   to strip off everything except the class name.

6. Use Text > Sort Lines… to sort the list.

7. Use Text > Process Duplicate Lines… to leave only a single instance of each class.

Viola!

“Extract” is not one of the command options when you’re creating a text factory, but you can automate steps 5–7 by placing this file in ~/Library/Application Support/BBEdit/Text Filters/: Unwrap+Sort+Dedupe_classes.textfactory. Then, from your file of extracted occurrences, select Text > Apply Text Filter > Unwrap+Sort+Dedupe_classes.

Easy peasy.

I still like that the old method shows me which HTML elements each class is attached to, and also pulls out any locally applied style attributes. But the convenience of this two-step process outweighs those features, for me.

Because the video is video and my slides are about fiddly details, I’ve made my segment of the presentation into a PDF, so you can see what I’m talking about: “Making Beautiful Books” webinar slides (2 MB)

I don’t think I said anything too terribly incorrect, though I have a bad feeling that what I call a “deckle edge” is actually called something else by printers. Whatever. That’s what it’s called in the world of my head.

I realized also, as soon as we were done, that I should have added to the “Resources” list that among the people one should consult are those professional book designers I recommended hiring. Because of course one’s designers will have clever ideas about how one’s book could be made into an even more irresistible package, as @SCauleyDesign did with that spot varnish on Point of View New York City that I show in the webinar.

1. Yes, my portion of the presentation ran about fifteen minutes too long, because I hadn’t timed it beforehand and couldn’t see my system clock while screen-sharing the slides from PowerPoint. Sorry, Allan.

Although the Chinese-owned publishing company where I now am managing editor mostly produces English-only books, occasionally I do have to deal with Chinese characters in InDesign. This week, I started working on a series of dual-language poetry books that were previously published in China, and I want to rework these into a single parallel-text edition for U.S. readers, particularly students. Fortunately, the Chinese edition was set in InDesign—this is not always the case—so I’m able to rework the files we received from the original publisher.

Immediately I set about editing the style sheets—changing their names to ones I could actually read, for instance—and rejiggering things to enable matching the originals and translations across spreads, stanza by stanza if not line by line. In particular, I wanted to make the Chinese text slightly larger and the English text slightly smaller. I also wanted to replace all the English fonts with more tasteful ones and simplify the palette of Chinese fonts.

The Chinese versions of the poems in these books all have little pinyin pronunciation guides over each character, and at first I thought they were part of the fonts themselves. To my delight, however, I found that when I changed the Chinese fonts, the pronunciation guides stayed in place and scaled with the text. These pronunciation guides are, it turns out, called ruby annotations, and if you view the Chinese in InDesign’s built-in text editor, you can see the ruby label wrapping each character. (Don’t worry; a screenshot’s coming up.)

Unfortunately, the original book used a font that didn’t contain all the characters needed to set these poems. I don’t know much about Chinese fonts, but from my experience with Chinese-language files thus far, this seems like a common issue. There are several Chinese character encodings, and sometimes the glyph you need will not appear in the font you’re using. When this happens, sometimes the compositor will swap in a different font just for that character, or sometimes, as they did in these books, they will insert the missing character as one or more pieces of outlined type, grouped and anchored inline:

I assume this is done using some plug-in, or that it’s a thing the CJK version of InDesign handles automatically, but in any case, the ruby was somehow then wrapped around this anchored image. So when I changed the Chinese font and made it larger, these anchored images didn’t scale. Their ruby text did scale, but it was no longer aligned properly. I could scale the embedded graphic manually and move the ruby up using baseline shift, but nothing really lined up, the ruby was off-center, and the style of the glyph didn’t match the surrounding text, of course. Furthermore, I thought these missing characters might exist in the new font I’d chosen, and if that was the case, I’d far rather replace the embedded images with live text. If I just pasted in a new character, however, I couldn’t add a ruby label to it, nor could I move the new character inside the existing ruby tags to replace the anchored image, although I could see these in InDesign’s text editor view:

So I poked around in the InDesign forums and found a post by David W. Goodrich recommending World Tools Pro ($179), a post by Manish Sharma explaining how to launch the InDesign in CJK mode, and a post by John Hawkinson saying you can edit ruby if you pull the text out as a snippet. In the latter thread, Jongware posted a “Poor Man’s Ruby Editor,” but I didn’t try this; instead, I decided to see if I could figure out the snippet method.

First, I had to look up how to create a snippet, since I’d never done so before except by accident. But eventually, I came up with the following process.

1. Figure out what the Chinese character should be.
I can’t read, write, or speak one word of Chinese. I have no idea how anyone ever manages to type it on a U.S. keyboard layout. But I figured out two ways to identify these missing characters.

(a) Search for the pinyin transliteration using the pronunciation lookup at ctext.org

and then visually scan the search results until I find my character:

When I click on the correct character, I get a page of handy information about it, including any text on ctext.org that includes it.

In this case, I found text that (almost) matches my original, confirming that I’ve got the right one.

Alternatively, since my text is a classic and I’m pretty sure it’s online somewhere, I could just (b) search Google or ctext.org for a line of text above or below the one I’m working on, and find the missing character that way. This method is faster, and I found that in at least one case, the outlined character in the original layout appeared to be the wrong one, or the ruby label was wrong. (Yes, I’m going to have someone who actually knows Chinese proofread these pages, when I’m done; I’m crazy but not stupid. Or stupid but not crazy. One of those . . .)

2. Paste the correct character into the InDesign document next to the original one.
It pastes in at the right size and in the right font, and, sure enough the new font I’m using actually includes this character. Whee! However, the ruby label is missing.

3. Select both the Chinese character and the ruby-annotated graphic and Export -> Adobe InDesign Tagged Text.

I use the Abbreviated option, since I don’t need most of the gunk that will be in this file, and ASCII mode, since exporting as Unicode got me weird results when I tried it.

4. Open the resulting .txt file in a text editor. I use BBEdit, and I set it to display as XML, to add some color coding.

It looks quite formidable, but all I’m really concerned with is the last line. Here are the business parts of that line:

In fact, you can delete everything above this last line except the <ASCII-MAC>, to make it easier to see what you’re doing. The rest of the snippet code is mostly style definitions, which we don’t need since we’ll be pasting this snippet right back into the same document it came from.

5. Cut and paste the unicode for the Chinese character (item 3) over the space where the embedded image was in the original ruby wrapper (item 2). You can delete the trailing <cr:><crstr:>, so my entire revised snippet file is now just

6. Save the snippet and drag the file back onto your InDesign window. Click-drag to place the snippet.

Note how the ruby annotation sits completely above the top of the text box; it’s welded to that glyph, though, I swear.

7. Copy and paste the new rubyfied character into your text, replacing the old image and un-rubied character.

Now, how do you say, “Et voilà!” in Chinese?

It looks like a lot of trouble, but I can now round-trip a character in less than a minute, and fortunately there aren’t very many of these. Still, if there’s some easier way to do this, I’m all ears.

Yesterday at work I was generating price breakdowns for a bunch of POD printing situations, doing it the old-fashioned way by dedicating a separate chunk of a spreadsheet to each variation, when it occurred to me that maybe it would be easier to set up a dynamic calculator for these scenarios in Python, which I’ve been studying on and off (mostly off) for a while now.

Then it occurred to me that I might not even have to leave the comfort of my spreadsheet, since most such applications include functions for calculating and doing other useful things. I rarely use anything more complex than =sum(), but I know the other stuff exists. Mostly I needed to be able to set up conditional behavior, so as long as there was an if/then function . . .

It turns out that Google Spreadsheets, which is what I was working in, has an IF() and a host of other handy functions. So I stayed up way too late building that calculator, for which there was no real purpose, since I’d already sent my boss a static spreadsheet with the numbers he needed.

But then today I still had spreadsheet-based forms on my mind, and I decided to tackle a project that had been on my Python to-do list for months—namely, a castoff calculator. I had built a shitty one in PHP a few years ago for a class, and then I forgot about it so utterly that when I needed to do a castoff more recently, I searched online for a Web-based calculator and was shocked and appalled to see my own domain name in the first hit. That form is embarrassingly useless, but since I’m working in print book production again (more on that later, I guess), I might occasionally have to do a castoff. Now seemed like a good time to replace it.

Behold, therefore! Castoff Calculator. To use it, you must first make a copy of the document; instructions are at the top of the first sheet. Aside from that little inconvenience, I think this version is actually pretty sweet, and I had fun making it. It would have been easier to manage the calculations in Python, because reusable variables and functions (shoutout to the sensible coding habits I picked up from Learn to Program: The Fundamentals), but it’s hard to beat Google Spreadsheets for quick-and-dirty building and sharing.

Lemme know if you find this useful, if you find holes in it, or if there’s something else you think it should do.

Photo: Wang 700 Advanced Programmable Calculator by dvanzuijlekom; some rights reserved.