Posts Tagged ‘Technical Writing’

  • And the word of the day is… docragination

    on May 19, 11 • by Helen Abbott • with No Comments

    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 »
  • The Co-op Experience (Part I)

    on Jan 27, 11 • by Kevin Welsh • with 1 Comment

    The Co-op Experience (Part I)

    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 »
  • Lost in translation

    on Dec 16, 10 • by Patti Murphy • with 1 Comment

    Lost in translation

      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 »
  • Translation woes revisited

    on Dec 14, 10 • by Helen Abbott • with 2 Comments

    Translation woes revisited

    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 »
  • Wiki translation woes

    on Dec 7, 10 • by Helen Abbott • with 4 Comments

    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 »
  • Error messages: Moving beyond WTF

    on Jun 10, 10 • by Patti Murphy • with 3 Comments

    By the time users hit the help documentation, they’re already snarly. Yeah, some people read the documentation first before using the tool, but… A lot of people just want to dive in and start using the tool. And when I’m stuck I want answers. Now, already!  You might think it’s stupid-user error and I might think it’s stupid software design, but who cares? I want help right NOW. Troubleshooting information lives or dies by the search-and-I-better-frickin-find-what-I’m-looking-for mentality. How do we look for this help? We copy and paste error messages into a browser and search

    Read More »
  • Getting developers to RTFM

    on May 27, 10 • by Helen Abbott • with 1 Comment

    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 »
  • If you want users to RTFM, write a better FM

    on May 6, 10 • by Helen Abbott • with 9 Comments

    If you want users to RTFM, write a better FM

    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 »
  • Death by a thousand cuts

    on Feb 11, 10 • by Helen Abbott • with No Comments

    Death by a thousand cuts

    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 »
  • Limping through agile

    on Jan 21, 10 • by Patti Murphy • with 2 Comments

    Limping through agile

    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 »
Scroll to top