cellio | Entries tagged with writing

Someone on a tech-writing mailing list today asked the following: "As a hiring manager, what are you looking for in a resume? Do you think hiring managers with a technical writing background look for different things than one that is just getting to employee their first technical writer?" I want to record my response here:

I am a software developer and manager who was formerly a full-time tech writer. (I still do some writing, but it's not the majority of my work any more.) When I was hired it was for a sole-writer position.

What I look for in a resume is: technical expertise (what domains do you already know?), types of writing, size/complexity of past projects, and classes of tools. On this last: I don't care about the long list of tools (my eyes kind of glaze over, actually), just as for programmers I don't care about the long list of languages dating back to college. I do care about whether the candidate has worked with structured editing (e.g. XML) versus just working in Word. I care about whether a candidate has built or maintained the tool chain. But I don't really care if you've used Epic or FrameMaker. Tools are tools; I assume you can learn the ones we use. We'll sanity-check that assumption in the interview.

You may have noticed an absence of actual writing skills on my list. I can't judge that from a resume (except in the negative); that's what the writing samples are for, and they're essential. I want up to a few hours with them, not just what I can see while we're talking during the interview.

I don't have a lot of data about what non-writer hiring managers look for, but I believe the factors that got me hired by my current company were: technical skill (both writing and programming), ability to work with geeks, ability to work independently (demonstrated by past positions), and asking insightful questions about their software (showing that I wasn't going to just parrot what the SMEs told me, and also that I'd done some homework). (Granted, you don't get to demonstrate some of that until you get the interview.)

(Not posted on the mailing list because it would have been topic drift: For what makes an excellent writer in my particular domain, as opposed to just what I'm looking for in candidates, I find that an entry I wrote almost seven years ago still sums it up pretty well.)

( documentation, cities, religion, music )

I'm reading torah tonight (unusual) and tomorrow morning (not unusual). Part of the latter package is giving a short d'var torah (torah commentary), so for the last few days I kicked some ideas around in my brain and last night I wrote a draft. (I'm still on my written-text kick rather than speaking from notes.)

This morning in the shower I made a structural change, jetisoning about a third of it. During the morning commute I composed the new part and figured out the transitions. I drive to work, so this was (obviously, I hope) a mental exercise. When I got to work I spent five minutes writing down the revisions.

For all that I seem to have the mental buffer space for this sort of exercise, and for all that I'm told this is unusual, I still sometimes marvel at my inability to remember less-complex information.

(I do sometimes think about getting a PDA so I can record things easily while not at my computer, though I note that that wouldn't have made a differnece in this particular case.)

You know you're among geeks when questions like "but really, what is the true nature of a book?" make perfect sense. (A group of mostly tech writers and moi, discussing the partitioning of a doc set into DocBook-sanctioned units like sets, books, parts, and chapters.)

Quote of the day: ...And adjectives, like gang members, seldom ventured out alone. They went out in twos and threes, and God help us, fours, and piled up on any person, place or thing that got in their way. "Look! It's a noun -- let's get it!" -- Robert Masello, quoted by mabfan here. This is one in a series of excellent posts on rules of writing fiction.

Rabbi Micha Berger posted an article about types of halachic rulings that I found useful.

Some folks at work have been having the discussion/argument about the use of "they" as a singular pronoun. This usually boils down to a religious argument and hey, I know better, but today I sent the following message:

[We should be trying to communicate clearly, and sometimes language rules prevent that.]

I agree. This is why, when conventional language rules would dictate something that would make my writing harder to understand, I violate those rules. For example, I only place terminal punctuation inside a closing quotation mark if it is in fact part of the quoted text, because to do otherwise misleads the reader and is logically incorrect. That's not how the language rules evolved, but (fortunately) that's becoming a more common practice within the field of technical writing, and eventually we may be able to drag the rest of the English-writing world along with us.

This argument does not apply to singular "they", however. Or if it does, it doesn't apply the way you think it does, at least for some readers. If I see a well-crafted sentence that completely avoids the problem, I don't find myself thinking "wow, that was really unclear; he should have just said 'they'". Because it's well-crafted, I don't notice. That's good; one of the jobs of technical writing is to get out of the way so people can understand what you're writing about. On the other hand, every time I see a use of singular "they" that (I think) could have been easily avoided, it derails me in my reading -- exactly as an incorrect "it's" does. It distracts me from what I was doing -- absorbing communication -- and draws my attention to the writing itself. Further, that attention is negative; it lowers my opinion of the author or company whose work I'm reading. None of this is conscious and I can't will it away. I know I am not the only such reader.

While we should not necessarily write to the lowest common denominator, if one choice results in clear communication to everyone and another does not, we should follow the one that does, even if it's a little more work on our part. So quite aside from the (very real) religious arguments against singular "they", I hold that there is a practical reason to avoid it: it derails some readers and is not necessary.

A coworker and I had one of those mutual "you believe what?!" moments, and it was surprisingly educational and non-heated. Nifty.

We were talking about documentation that's meant to be viewed online. My favored format there is HTML; he was advocating PDF. And when we had peeled away the surface issues, it turned out that our user models are fundamentally different.

( Read more... )

I rarely write fiction (well, other than in

ralph_dnd, but that's different), but this bit of whimsy struck me earlier today.

( Read more... )

Today I learned that one of my favorite grammar/usage curmudgeons has a blog, which I've now syndicated:

bill_walsh.

Bill Walsh is the author of Lapsing into a Comma, a sensible style guide with interspersed rants. Just my kind of thing! Also see Rules That Aren't, a response to some commonly-held "rules" like not splitting infinitives. (And hey, apparently he has a new book out. Must investigate.)

I don't agree with everything he says, of course, but he makes solid, often-entertaining, arguments for his points instead of just saying "thou shalt do X".

If the application comes with a "getting started" document, I expect that document to tell me the few things I need to know to get going. I don't generally expect a 42-page document for a simple application. This is calendar software (client-side, not server-side), not Oracle.

I further do not expect the section entitled "quickstart" [sic] to begin on page 33, after the instructions for installing and uninstalling. Hello: this document auto-launched at the end of the installation; I probably don't need those first 32 pages just at the moment. (Granted, a few pages are about installing on and syncing with a palm device, but I'd still expect "usage 101" to be front and center in such a document.)

While I'm on this roll, if I just upgraded from version 8.0 to version 8.5, release notes entitled "what's new in versions 8.0 and 8.5" aren't especially meaningful to me. Is it too much to ask for what's new just in the version I actually installed?

Someone recently asked me if I have any advice for someone at his first tech-writing gig. Asking me quesions like that is sort of like dangling tuna in front of the cats. :-)

( Read more... )

Nick asked me these questions a while back, but I never got the email notification and I didn't notice. If anyone else thinks I'm ignoring questions, please let me know.

1. How has the field of software documentation evolved during your career?

( Read more... )

2. How did growing up in the SCA community in particular influence who you are now? Would you have grown into more or less the same person in a different social environment, such as your current congregation?

( Read more... )

3. If you could become a pen pal of any person from any time, with whom would you correspond? (To avoid paradox, assume that the person exists in a parallel universe, so you could even correspond with yourself from the past without causing reality to implode.)

( Read more... )

4. Alternatively, what do you do if the genie allows you to undo after seeing the consequences? Specifically, you may once instantly revert reality to a backup copy of the moment before he would have contacted you. Does your answer change if you could remember your experiences from the forked reality?

( Read more... )

5. How would you characterize the stories that you most enjoy reading or watching? How have these desiderata changed over time?

( Read more... )

Here's how this works:

If you want to be interviewed, leave a comment saying so.
I will respond, asking you five questions.
You'll update your journal with my five questions and your five answers.
You'll include this explanation.
You'll ask other people five questions when they want to be interviewed.

( conversion reactions, writing, LJ, tastes, fixing Pittsburgh )

This question is directed toward two groups: people who have completed fiction works, and people doing NaNoWriMo (national novel-writing month).

How do you structure your writing? Do you write your story linearly from beginning to end (not counting editing passes)? Or do you jump around, leaving place-holders for things you'll fill in later?

My impression, based on only a few data points, is that people doing NaNoWriMo tend to start at the beginning and write the story in order. (NaNoWriMo is all about cranking out the initial draft in a short period of time, so editing is discouraged.) I write fiction rarely and as a hobby only, but I've found that I tend to jump around somewhat -- I may start out writing linearly, but then I'll insert something like "[wild night in bar goes here]" so I can write the next part, because I'm not feeling inspired to write about wild nights right now but I do have inspiration for the aftermath. Do people who write fiction more seriously do that, or am I just quirky?

I find myself wondering whether NaNoWriMo builds productive habits, encourages destructive habits, or is just plain orthogonal to conventional writing.

( Read more... )

On a tech-writing mailing list people were talking about red flags in resumes (for tech-writing positions, I mean). Most people were talking about content issues, so I raised formatting.

Specifically: if you send me HTML (or a URL) I will inspect your source, and if you send me a Word document I may examine the structure of your document. (Word isn't a core tool at this job, so I don't care as much -- but I still care a little.) This is because I care not just about what you write but whether you have some basic tools-usage clues. For example, I've seen resumes that claimed HTML proficiency, but when I looked at the source I saw that it was Word's generic export (which is really really awful HTML). If you and I (and the hypothetical other members of my team) are going to be working on the same source files, that won't do. Similarly, I'd like to know if you're using headings or hand-modifying those paragraphs to be bold and a bigger font. Stuff like that.

Someone complained that I put too much emphasis on tools, but I don't think I do. I haven't set the bar especially high, and it's one of several factors I consider. But I consider poor use of tools on the resume or submitted writing samples to be in the same broad category as awkward writing and grammatical errors -- everyone makes those mistakes at times, but if you do it on something as important as your job application, how much will you do it once I hire you?

If I were interviewing a programmer who showed me a really snazzy demo, but the source code was a tangled unmaintainable mess, I wouldn't care too much that he'd written snazzy code, because he wrote code that no one else will be able to maintain (and that he probably won't be able to maintain in six months). Doc source is no different. Your content and your methods have to be good or there will be long-term pain. If there's going to be long-term pain, I'd like you to do it somewhere else. :-)

I'm not saying that I'm going to reject the otherwise-perfect applicant who uses a hard-coded "bold + font+2" or whatever, but it's not the otherwise-perfect applicants who have to worry anyway. It's the folks who aren't clearly better than the rest of the pack.

As an aside, I personally don't send Word source files any more unless that format is specifically requested. I send PDF instead. Different versions of Word render differently, and I've seen some pretty bad formatting that I'm pretty sure the sender didn't see on his end. I don't want that to happen to me.

(Written Wednesday.)

On the ground Atlanta was dark and dreary, but as we emerged above the cloud layer the view was (and still is) breath-taking. The sun is nearly at the horizon (that is, the cloud-horizon), and the yellow-orange light plays beautifully across the "ripples" in the clouds. Baruch ma'aseh b'reishit (blessed is the source of creation), or words to that effect. (There actually is an appropriate blessing for situations like this, but I don't know what it is and my siddur is in the overhead compartment.)

If there was any doubt before now, I now know that the travel agent who booked my flights isn't touching my future travel. I'm too big for middle seats on airplanes. Sheesh. Fortunately, that was only for the Memphis-Atlanta leg. The flight from Atlanta to Pittsburgh is sparse enough that I wonder about choice of plane. How far in advance do they have to commit to the plane, I wonder? Do they even take purchased tickets into account, or do they just have heuristics about the source, destination, time of day, and day of week?

( some conference notes )

( food )

Short takes:

Either the wireless card or its configuration for this laptop is broken. (So maybe the Pittsburgh airport does have wireless access after all.) Fortunately, the wired access worked fine, so I could access the net from my hotel room if not from the conference center.

FedEx sponsored a building ("FedEx Institute of Technology") at University of Memphis. (This is where the lab we toured on Monday is.) It was a little odd to hear people talking about "running over to FedEx" when they weren't talking about shipping packages. :-)

I didn't know that the idea of design patterns existed in (physical) architecture long before it existed in computer science. The relevant name here is Christopher Alexander.

Michael Priestley (from IBM in Toronto) looks really really familiar, and he thought the same about me. We were both at SIGDOC in 2000, but I don't think my memory is that good, and I don't think I did anyhthing to draw attention to myself there. (It was a larger conference, so it was easier to be invisible.) I wonder if I know him from somewhere else and, if so, where. I'll have to see what Google says about him. (I wonder if he'll be doing the same thing. :-) )

The attendance seemed to be about evenly divided between academics and industry folks. You could sometimes tell that they live in different worlds.

An interesting possibility for collaboration developed tonight. I spoke for a while with another programming-minded writer who has some good ideas for modeling documentation for maintainability and modularity. We might work together on this.

On a different subject, the folks at the Institute for Intelligent Systems are doing some nifty work on assessing effectiveness of text (and other content). One of their systems, QUAID, evaluates survey questions (e.g. for pollsters, the census bureau, etc); it shouldn't be too surprising that a lot of people don't actually understand the questions before they answer them, and they confirmed this with (among things) eye-tracking devices. Anyway, the tool suggests modifications; it doesn't compose text. But it did a pretty good job on the examples we threw at it.

Along similar lines, Coh-Metrix suggests improvements to the readability of arbitrary text passages. (The "coh" is from "coherence".) Often their suggestions are not the ones that come from those "simplified reading level" efforts popular with school texts. In fact, they found that precisely following those guidelines actually hinders above-average readers, because sometimes you need to not connect all the dots to stimulate analytical thinking by the reader. Spoon-feed it and some people never actually absorb it. Interesting.

AutoTutor uses NLP techniques that seem familiar (:-) ) to build dialogue into tutoring software. So the software poses a problem to the student, the student types questions, candidate solutions, and random speculation into a window, and the tutor responds in ways that are mostly appropriate to guide that student toward the answer. They're using latent semantic analysis, comparing the student's utterances to an ideal answer. Kind of like the way Clarit retrieval works, it sounds like.

Attendance is about 50/50 writers and programmers. This is, apparently, typical for SIGDOC.

I'm getting some ideas for ways to better QA our documentation, though none fully formed yet. Tomorrow has some promising sessions toward that end.

I wonder whether my coworkers never read my documentation, or whether they think my sometimes-frank writing is ok. The following has been in the documentation of one of our examples for a month or two now with no complaints: "This is an advanced example, relying on the under-documented internals of [package]. We will not attempt a complete explanation here, and will focus primarily on [one feature]." Yeah, I considered not including that example at all, but there's some valuable stuff about [one feature]...

Tonight I got together with my co-chair (worship committee) and we assigned all the parts for the high holy days. We have double services and parts in both Hebrew and English, so someone first collects all the relevant data from the board members and officers (the people who get parts). Then we do the giant jigsaw puzzle to make it fit with who has what reading skills and will be attending which services. After last year's session with pencils and erasers (the way it was taught to me), I had a good idea: post-it notes. On each note, write one person's name and constraints. Apply post-its to order-of-service pages; shuffle as necessary. When satisfied, transcribe. Much easier. I actually don't think doing it electronically would be faster.

short takes:

A programming koan from jducoeur.

Allergen-free cats -- sounds like a hoax, but cute. (Link from ommkarja.)

I just received (at work) a phone call from a consulting firm. It was pretty obvious that he was calling to either (try to) recruit me or sell services to me, depending on how the first 30 seconds of the conversation went. It was pretty amusing. He apparently doesn't get a lot of "actually, I'm very satisfied with my current position and company" these days. :-) But they might actually have some relevant services, so it wasn't a waste of my 15 minutes either.

(Specifically, if someone could come in and affordably wave the DocBook [1] magic wand for us, with fairly painless migration and all the flexibility we currently have, I'd lobby for that expenditure. There are important things that my current tools can't do and that, apparently, DocBook can. But I don't have the cycles to climb the steep curve right now.)

[1] Or maybe we should be looking at a different tool instead. That evaluation would be part of the job.

When did you first discover the net?

In college, and in stages. I first encountered the idea of email in 1979; I knew there was a bigger world out there, but as a student I was limited to campus email addresses. In, I think, 1982 I got a job with the CS department, which as a side effect got me my first account on a machine with ARPAnet access. I discovered the SF-Lovers digest, but little else, and I didn't know anyone outside the university who had email. In 1984, after I graduated but while I still had a legacy account, CMU got Usenet and I got sucked in for a while. (There was no reader on the box on which I had an account; I read articles directly out of the spool directory over the network for long enough to decide that this was interesting, and then wrote a reader.)

What inspired you to pursue a career in technical writing?

I blundered into it by accident, really. I headed off to college in pursuit of CS. CMU didn't have an undergrad program at the time; what you did was to major in applied math and load up on CS courses. Well, the CS stuff was cool but the math was frustrating; for a program with "applied" in its name it seemed awfully uselessly-theoretical to me. While angsting about this I talked with someone who said "you have an aptitude for writing; why don't you do that?". I said "what, journalism? you can't make a living doing stuff like that". Then this person told me what technical writing was, and that sounded nifty and I ended up changing majors. I took almost all of the CS courses that I would have taken as a math major, by the way.

My first position out of school was at a startup as half tech writer, half programmer. Eventually the company got larger and the management structure got weird and I had to choose one, and because of things that were going on at the time I chose the programming route. I remained a programmer through one more job change, and come the one after that I realized that I was an adequate programmer but could be a good tech writer in the right kind of position. I found a company that was looking for a tech writer to document programming interfaces and software design and such, which was perfect. Now that's the kind of position I seek out, and so far I've been decent at crafting a position to fit what I can offer.

If I ever find myself irrevocably writing "application software 101" -- you know, "from the file menu choose 'save', type a file name into the dialogue box, and click on the 'ok' button" etc -- I think I'll have to take it as a sign that something has gone very, very wrong, and maybe it's time to bail.

Who has been your greatest influence?

My father. Both of my parents are great -- they were always there and supportive when I was growing up, very nurturing, and so on. But my father, in particular, is the one who was always challenging me to think harder and to do things I didn't think I could do (ranging from riding a bike to solving polynomial equations). My father is very smart, and he realized that I could be smart too but that's not just about schoolwork. He taught me to be analytical, inquisitive, and persistent, and I think two of those stuck pretty well.

If you could live at any time and place in recorded history, when and where would you live?

There are lots of places I'd love to visit, but for actually living, I don't really want to give up the benefits of modern medicine, instant communication with a large number of people I'd never know otherwise, the (pretty-much) guarantee of a comfortable home and ample food, and the ability to pursue whatever interests me regardless of class, gender, family background, etc.

What do you think is the best way for the US to balance the need for national security and individual privacy? ( Read more... )

You know the drill: if you want a set of questions, ask. You'll update your journal, including the offer to propegate.

Seasonal food question: What goes well with latkes? I don't mean the sour-cream-vs-applesauce question; I mean: what (dinner) main courses work well with potato pancakes? Suggestions for dairy (or parve) options are especially welcome, but meat is fine too.

We pretty much completed our holiday shopping (for my relatives) last night. Not only did we go to some actual physical stores, but we even ventured into a mall. Haven't done that in years, but the only local instance of a certain store was in the mall, so off we went. It was surprisingly uncrowded. I wonder if that's because shopping is moving online, because we're between waves of shoppers (the ones who were done in October and the ones who will start on December 23), or because people just aren't shopping as much. As a bonus, yesterday featured the good weather for this week.

We did a chunk of our shopping online, of course (we rarely go that long between instances of giving Amazon our money). But sometimes you've just got to see the item in person.

The release of Blake's 7 on DVD has been delayed yet again. Amazon.uk sends the most polite apologies for things beyond their control, in contrast to most US companies. And it's not like they have my money (only my credit-card info), so I couldn't possibly have any complaint against them. I wonder if the BBC's plan to put all their old stuff online will preclude DVD releases. I don't want to watch TV while sitting at my desk; I want to watch it while sitting in the comfy chair in front of the 32" TV.

I've been doing a lot of D&D catch-up in ralph_dnd. One more major missive to go, and then I'll be caught up to where the characters are. I don't usually write fiction, and this is only semi-fiction because it's reaction to events that have occurred in a shared game -- which is probably why I can write it at all. I've never been very good with fiction, but I seem to do ok when I've got hooks into a set of characters.

I've been meaning to write a proper review of The Kiruv Files for a couple weeks now, but I probably won't get to it this week either. Next week, maybe. If I keep saying that, it'll be true eventually. :-)

Tonight's commute featured ugly traffic snarls. There was an accident on 376 that closed the road in both directions for a while; I don't use that highway, but there was spillover. What surprised me was where the spillover was; after sailing through what I thought would be the worst part, I spent 15 minutes going about two blocks near my house. Unfortunately, those two blocks were right after the point where I could have made a better decision. Oops. :-) (Mind, the accident was around 4:00, and I was doing this after 6:30...)

I wrote some user documentation for a feature. The concept is general, but there is only one concrete case within the UI now (and for the forseeable future). Being an abstract-thinking, API-focused, programemr kind of person, I wrote an abstract description using a concrete example. That's what everyone would do, right? You don't want to limit the future usability of the document, after all -- generality is good.

This will, apparently, confuse the users. Everyone knows you can only do X to a Y, so a discussion of doing X to Y, not X to {group including Y}, is needed. I am assured that this is true.

I can't trade in our users on different ones, so I guess I should simplify the document. If they add a second case of this next quarter, though, I reserve the right to mock someone. :-)

One of these years I may make a real effort to compile some of what I do into the beginnings of "Tech-Writing Pearls", but for now all I'm doing is stashing stuff away when I realize I've written something that could be fodder later. Like now. :-)

On an API-documentation list someone asked about verb choice for access methods -- "returns", "gets", "retrieves", "queries", and so on.

I strive to be very careful to expose the correct amount of implementation in the documentation. That is, sometimes we only want to promise that we return a value somehow. Other times, we want to convey to the user that a new computation (e.g. a database query) is happening, which should affect the conditions under which he calls the method. So, using a word that implies computation when we're promising not to compute actually makes things worse.

I use "returns" almost universally. If we're actually computing or fetching a value, and this behavior is part of the interface specification, I'll say that, but I'll also try to get the programmers to name the method something other than "getFoo" in that case, too.

I view the method itself as the subject of the sentence, so I dislike "gets" because that's not what the method does. Your code is getting a value by calling the method, but the method does not "get", it "returns" or "provides access to". This may seem like excessive anal-retentiveness, but there can be cases elsewhere in an interface where it is not at all clear where the work gets done, and I find that if I am stubbornly consistent about using verbs that apply to the method (rather than the caller), I can reduce the potential for confusion elsewhere. My readers can learn the pattern if there is a pattern.

Update: I intended to focus here on what to say in the documentation, and not how to design the API, but I probably didn't make that clear enough before. Sorry 'bout that.

Ok, I'm a geek. But it'll be good for the project, once they get used to it. :-)

Our company makes an SDK (software development kit). That means that we sell our product to people who then use it to make their own products. We provide documentation for those programmers. We also provide the building blocks of a user interface, which they can use or not.

It was only a matter of time before we had to start worrying about user documentation for that interface. Now, we can't just do up a user guide for the interface, because our customers can modify it and need to be able to produce their own customized user guides to go with. And we can't, it turns out, just make them do all their own user documentation. (We currently provide a quick-start guide, a UI cheat sheet of sorts.)

So I'm now thinking in terms of a "UDK", a "user doc kit". Like the SDK, we would supply building blocks and they would put them together as best suits their needs. As with the SDK, we would provide a basic implementation that makes sense and that they can use if they like.

I know I'm not breaking new ground here, but I'm enjoying thinking about the parameters of the problem so I can structure it appropriately. (It even makes up for the prospect of having to write some of that user doc...) We need to support people using everything from HTML to Word to Frame to some Mac-specific PageMaker-like tool (I don't know its name), so it looks like I'm going to settle on unformatted text files and standard graphics formats (JPG, PNG, etc) as the portable common format. I'd like to do something a little richer than that; we'll see. (I proposed XML or HTML but they didn't like that.)

We have a project in-house that needs user documentation, so I'll have a handy guinea pig. They asked me for help with user docs; I sold them this approach instead, which is generalizable. It would be stupid to just do a project-specific user guide and later raid it, cut-and-paste style, for the next project that needs this. Besides, this way we can package the bits for customers, too.

You can still ask questions here.

( Read more... )

Monica

tech-writing resumes

interviewed by merle_

writing and memory

short takes

singular "they": a practical objection

documentation: the assumptions behind presentation

a story

for the grammar geeks

documentation nits

technical writing 201

interviewed by nickjong

interviewed by amergina

a question for writers

interviewed by alienor

evaluating resumes

notes from 29,000 feet

conference notes

random bits

buying or selling?

interviewed by gregbo

short takes

a lesson in user documentation

tech-writing geeking

documentation toolkit

answers, part 2

Expand Cut Tags

Syndicate