I came to the practice of procrastination late in life. I was always one of those annoying people who arrived for appointments early, handed in assignments early, went to bed early. Becoming a full-time working parent drove me to the dark side. Now I’m routinely late — late for exercise classes, late going to bed, late getting the kids to daycare. My forgetfulness factor has increased about 26-fold too. I’ve always been a list-maker, but now I have a few sayings that my husband is sick of: If it’s not in my calendar, it’s not
Read More »
After six years of post-secondary education, my first day of the real world had finally come. As I approached the doors to Klocwork, I realized it was time to put all my years of education to the test. Straight out of high school, I had little idea of what career path I should take. Four years of university passed and I graduated with a B.A. in English, but still, I didn’t feel prepared. Another two years of college in media-related studies and, ready or not, it was time to make the leap into the working
Read More »
Do internationalization and localization take the fun and flexibility out of documentation? And here’s the answer: You betcha, sister! At the risk of starting a brawl in the documentation department, I’m going to respond to my manager’s post about our new policy to facilitate the translation of our wiki . It’s a policy I refer to unaffectionately as the Stamp-Out-Fun-and-Flexibility policy. And yeah, I know that internationalization and localization are important to humanity and, um, sales. It’s just that making things more translatable makes documentation less agile and less fun. 1. Wikis are agile
Read More »
In a previous post, I discussed the problems we encountered when considering translating our entire MediaWiki-based documentation suite. I talked about how to get content out of the wiki for translation, and then get translated content back to our users. In this post, I want to discuss translation and globalization requirements more generally, and how our small, agile doc team, working in MediaWiki, handles each requirement. Fulfilling these requirements results in lower translation costs and easier translation: Provide a medium for the translated documentation that accommodates text expansion Use preformatted styles Minimize the amount of
Read More »We moved all of our user documentation from Author-it to MediaWiki a few releases ago. At that point, we translated only a part of our documentation to Japanese – the help pages for detected issues. For these wiki pages, we used MediaWiki language templates to display language links at the bottom, and we copied-and-pasted the translated text. For our most recent release, we expanded the translation effort. This meant more copy-and-paste – from the wiki to Microsoft Word, to send to the translator, and then from Word to the wiki, when we received the translated
Read More »Documentation is the castor oil of programming. The managers know it must be good, because programmers hate it so much. Gerald M. Weinberg I used to be a strong believer in formal doc reviews. Distribute a draft, plan a meeting, and have everyone gather around the table. But in the last few years, my team has moved towards mostly meetingless reviews–because people hate review meetings (you know, like code reviews, only worse), because people haven’t always read the drafts when they get to the meeting, and because some of our dev team is overseas. First,
Read More »
When I was documenting a new refactoring plugin for Vim, I checked out the Vim web site, and came across this blasphemy: Vim isn’t an editor designed to hold its users’ hands. It is a tool, the use of which must be learned. Later, someone sent me this beauty, from Elitist Jerks: Stop being lazy and read. Are users lazy? Do they expect hand-holding? Do they expect one button and no manual? Or is this more true to life? In the end, it probably comes down to this: Make tools usable. Then technical communicators can
Read More »
As a manager of a small tech writing team in an agile environment (are there any large tech writing teams left out there?), it’s easy to lose myself in how-the-heck-can-we-keep-up-with-myriad-coders-frantically-coding thinking. So when my manager scheduled a meeting to ask what innovations my team has planned for the next release or two, I thought of a few choice responses, such as “Um… how about documenting the new features in time for release? Is that innovative enough for ya?” and “Innovate THIS.” Eventually I calmed down, since he’s the boss, and I have a mortgage.
Read More »
I’m a technical writer who’s a big picture kind of person and that means agile development is sheer torture for me. Going into my second agile project, I thought I would be able to go with the “flow” a bit more. I was wrong. But, it’s important to point out that our documentation team hit all of our deadlines for new features, while substantially rewriting our help set and moving it to a wiki. I’m pleased with the outcome, but the trip was not pleasant. This will be my first post in a series about
Read More »
