Larry Hosken: New: Tag: writing

Book Report: Shady Characters

Thursday afternoon, talk at work turned to punctuation. Since work uses a lot of @s and #s, this should not surprise you. Someone hazily remembered that Shakespeare had invented “modern quotation marks.” This morning, I got around to Googling it: alas, that hazy memory was off. So… who invented quotation marks, then? Teh internets have some good info, but for more detail and analysis, I turned to Shady Characters, the book by the author of the Shady Characters blog. It talks about quotes, semicolons, dashes of various lengths… It's a fun book if you're into that sort of thing. There are some surprisingly good stories in there; how does a society figure out how to express a pause with no precedent? (It's kinda like figuring out that zero is a concept that merits a notation.)

Shady Characters has nudged the course of my life in recent years.

A few years back, some folks put together some resources to help folks learn the arcana of puzzlehunts. (Yes, there are mysteries, customs. Thinking about answer-extraction yields insights that let you skip parts. You are expected to recognize the six-dot Braille alphabet; you are not expected to know Braille contractions, eight-dot Braille symbols… That kind of thing.) Scott Royer had written an awesome puzzlehunt guide with a walkthrough for one puzzle. I was working at Google's engEDU team, hearing about Instructional Design and Theories of Learning all day. There are plenty of those Theories running around, but most agree: if you want someone to remember what you just taught them, give them a way to apply what they learned right away. So we wanted some more sample puzzles as exercises: nothing super-amazing, but something straightforward for Morse code, something for anagramming, something for indexing… Writing a puzzle with the only constraint "It should use Morse code" ain't so easy—you can do anything. If we had a theme, that would jump-start plenty of puzzles. But what theme?

I'd been reading the Shady Characters blog, reading about the history of punctuation. Most of these stories are of the form: over history, several symbols indicated the same thing. Before there were modern quotation marks, there were: different marks out in the margin, indented text with marks at the left edge; marks at the left edge with a different mark embedded in the text; different marks embedded in the text. But #'s story in the blog was different: # had been around roughly forever, but it meant different things over time and was called by different names.

So I used # as the theme for some sample exercise puzzles. Because # meant different things, there was still some variety. Several months later, there were quite a few puzzles. As the blog continued, more puzzle ideas resulted. Someone familiar with Swedish pointed out that # was a map symbol for a lumberyard. As you would expect, that inspired some lumber-ish puzzles.

Anyhow, when the book came out, I picked it up. It's a fun read; it's probably smoother to read the book than to pick your way through the blog. Usually, I'm a Kindle kind of guy, but I'm glad I got this book on paper. So far, most of the history of punctuation is tied up with the history of printing: scribes' marginalia, early typesetting. The physical book illustrates a lot of the type-ish things by using them itself; I suspect that wouldn't work so well on a Kindle. I read it over, got yet more puzzle ideas. But you might like the book even if you're not using it to get puzzle ideas.

Permalink
& Comments

Book Report: Confluence, Tech Comm, Chocolate

I'm a technical writer. I understand that folks don't always appreciate technical documentation. Sometimes the docs are bad. Sometimes the docs are good…at bearing bad tidings. Tech writer Roz De La Torre talks about some review meetings with engineers about draft documents.

Them: "This is terrible. This is way too complicated"

Roz: "Is it wrong?"

Them: "No."

The book Confluence, Tech Comm, Chocolate is for, by, and about technical writers. It's about keeping documentation in a wiki. I didn't learn so much from that part; I've been keeping docs in wikis for several years now. But it was specifically about Confluence wiki, and I'd heard that it had a section on how Confluence's search computes relevance ranking. We use Confluence at work, so there were some things I wanted to know about; how to do "intranet SEO" was a big one. From that I learned… Confluence's search doesn't work the way I want it to. Findability isn't a big problem for us now; but it probably will be sometime in the next couple of years. And we might not have great tools to fix it then.

This is terrible.

By which I mean, "Thank you for the early warning."

Permalink
& Comments

Book Report: The Art of Explanation I'm a tech writer. "Professional Ignoramus" would be a more accurate job title, albeit not so likely to land me fun jobs working with clever software developers. Still, it's what I do. Here's what ha...

Permalink & Comments

Link: Audience and Technical Writing E Nashif took some time off from studying to riff about Audience in technical writing. Audience, composition classes, and technical writing Audience, technical writing, ownership, etc (part 2?) O...

Permalink & Comments

Link: Drawing versus Writing Pencils If you doubted my sharp-pencils-aren't-so-great rant, check this out: Drawing versus Writing Pencils. Focus on the user; the ideal pencil sharpness follows the user's intent. ...

Permalink & Comments

not exemplary I laughed at @sec_reactions so much that I decided to make a Tech Writing Reactions tumblr. But then I realized that would take effort, so instead I just captioned one Star Trek photo. ...

Permalink & Comments

Book Report: How to Sharpen Pencils I'm a technical writer. I write instructions. I often team up with a "Subject Matter Expert," someone who's really good at doing something. I ask them what they do and they write it down. You might w...

Permalink & Comments

Scala, part of the new gig Bumped into @kberg and @adamsah yestere'en. We talked about work. They said interesting things which I won't repeat because oh man what if one of them accidentally let slip some confidential informat...

Permalink & Comments

Presentation: Tech Writing for non-Tech Writers I'm a rara avis at Twitter, the only full-time technical writer. As such, my life is that of a celebrity: I'm constantly being invited to events, everybody wants to be seen with me, etc etc. At least...

Permalink & Comments

@ikai pointed out an unintentionally funny article The Real Reason Silicon Valley Coders Write Bad Software. The reason? Because they aren't better English writers. This article made it into the Atla...

Permalink & Comments

Twitter is Hiring a Tech Writer ...or maybe more than one. I dunno, @JoinTheFlock is mysterious to me. I didn't even know the listing was up until someone told me. Am I under a non-solicit thingy with you? I.e., do you work at Goo...

Permalink & Comments

From the list of recent edits to Scala School, a tutorial for the Scala programming language, you might guess that puzzle nerds were trying to sneak in some easter eggs: You'd see a bunch of changes ...

Permalink & Comments

Link: Your free software website I am a technical writer. Within technical writing, as with other kinds of writing, there are genres. Genres are defined by rules. If you want to write the web page for an open-source project, these a...

Permalink & Comments

Puzzle Hunts are Everywhere Is [some of] your team hoping to head to Portland for The WarTron Game? If so, I'd like to tag along as an "embedded reporter". I.e., I'd play the game with y'all and write it up afterwards. Folks ar...

Permalink & Comments

Puzzle Hunts are Everywhere, and worth documenting if you ship them to Seattle or something I'm catching up (caught up now) on Snoutcasts, and just listened to the BANG 28 Debrief. You might wonder: what information was in the BANG 28 puzzle playbook? Folks kept raving about it (and about t...

Permalink & Comments

As a professional technical writer, I am always on the look-out for documentation "success stories." Documentation, when done right, can improve lives. For example, this evening on the bus ride home...

Permalink & Comments

Book Report: The Art of Game Design The Art of Game Design is pretty awesome. This book is about design. In theory, it's about game design. But if you're designing something for humans, this book contains plenty of wisdom. I think thi...

Permalink & Comments

Link: MobNotate The next time someone wants me to mark up their manuscript, I might suggest they use MobNotate to gather feedback. ...

Permalink & Comments

Technical Writing Student Internships Google is taking technical writing interns this summer. Yeah, everyone at Google's a genius and should never ever need anything explained to them. OMG especially not by some wet-behind-the-ears compu...

Permalink & Comments

If you recently guessed SCOUT VAILLANCOURT FOUNTAIN in the 2-Tone Game, try entering SCOUT again. I tried to clarify the wording a bit. If you didn't guess SCOUT VAILLANCOURT FOUNTAIN, then carry on...

Permalink & Comments

"What is a Content Management System?" At the GC Summit, Debbie mentioned that the organizers of the excellent DASH treasure hunt game will start using a content management system to keep track of their puzzles. Someone in the audience a...

Permalink & Comments

Updates:

Tags