Monica

• Here's why you're not hiring the best and brightest: (Jeff Atwood) talks about making telecommuting work so that you really can hire the best employees, as opposed to the best employees willing to live in a particular location. I once applied for a telecommuting position at a company that seems to get it as far as that's concerned, and a lot of the stuff they do is reflected in this article.
• What do programmers care about? (20-minute video): Joel Spolsky (Stack Exchange, Fog Creek) talks to recruiters about how to recruit programmers. If you've read Joel On Software you already know a lot of what he has to say here, but I still found it interesting to watch.

Can you help? Somebody asked a question recently on Writers about guidelines and heuristics for when to use screen shots in technical documentation. The question isn't looking for opinions or what you, personally, do but, rather, formal guidelines along the lines of what GNOME does for its documentation. So far it's only attracting opinion answers. I, too, have opinions and practices that I follow, but I can't source them either and I'd like to see the question get a good answer.

Speaking of Writers, I wrote a little something about writing good API reference documentation (like Javadoc), based on advice I've given informally over and over again -- finally wrote some of it down in a public place. Feedback welcome.

I recently saw an article with interesting-seeming observations and analysis of Modern Orthodox Judaism. I'm not all that tuned into the MO community and can't evaluate its credibility from inside, but I found it an interesting read. If any of y'all would care to tell me where on the spectrum from "yup" to "WTF?!" this is from your perspective, I'd be interested.

Finally, a little something for those who use the text editor vim (which I gather is related to vi?):

.

Part of this meme:

LISP

The most valuable part of my education as a technical writer was my student internship with the Common LISP project. It was also either the first- or second-most important part of my education as a software developer. Yes yes, the classroom stuff was important and the software-engineering project course was essential for putting the pieces together, but this was the real world and the real world is far less tidy than the classroom.

I was brought on to help write the documentation for this then-in-development language. (Other varieties of LISP existed; this was an attempt to unify them.) But unlike all previous tech-writing work, this was for a thing that did not fully exist yet, and I was part of the ongoing design process. I was there in the (virtual) room with the lead designers, Guy Steele, Dave Moon and dozens of others big and small, and if my contributions had merit it didn't matter that I was an undergraduate with no real experience. On the ARPAnet nobody knows you're a dog undergrad. Mind, being an undergraduate with no real experience, I didn't necessarily have a lot of design ideas to contribute, but even then I was pretty good at catching inconsistencies and asking key questions. I learned to write software-interface documentation there, but even more importantly I learned to be part of a real software-development process, to ask questions even if they might seem "stupid", to argue for technical positions and support those arguments, and to be a full member of a team.

When I graduated and met more of the real world I would learn that it usually doesn't work like this. In a lot of places, tech writers are not part of the development process (and may not even be in the development department) and the attitude is that they can come in after the big boys are done developing the product. Phooey on that; this important early experience taught me that it doesn't have to be that way, and I have held firm on this in every place I've ever worked. If I hadn't had this early lesson, I might well have fled the field.

It is also because of the Common LISP project that I went into programmer documentation (and expanded from there). I wouldn't have pursued tech-writing jobs that were all about walking the menus in the UI and stepping through wizards and such; I want to look under the hood, understand what's there, and use that knowledge to help users. Building software development kits like I do now is exciting and nourishes my inner geek. When I went to college I hadn't even heard of technical writing (I went there to do computer science), but I came out as a technically-proficient writer who knows the good that is possible. I have Common LISP to thank for that.

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.)

[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.

ralph_dnd

( Read more... )