Posts Tagged ‘Documentation’

  • Lessons learned in localization Part 1: Documentation pain

    on Sep 27, 12 • by Patti Murphy • with 7 Comments

    Lessons learned in localization Part 1: Documentation pain

    The big story for our Klocwork Insight 9.6 release was localization for our Japanese market. Prior to this effort, we provided a Japanese version that included a translation of a small portion of the documentation set. Since we’re magnanimous, we felt that others should benefit from our suffering lessons learned from this endeavor. Originally, I’d hoped to do a video for this entitled Crying While Localizing in homage to that fun meme Crying While Eating. But asking one’s colleagues to blubber on camera for minutes at a time while confiding their frustrations was a little too

    Read More »
  • 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 »
  • Klocwork Developer Network Set to Go Live

    on Mar 22, 11 • by Alan Weekes • with No Comments

    Our dilemma: How do we remove the barriers to knowledge about Klocwork's toolset, and developer best practices for creating high-quality code? The answer: Klocwork Developer Network--a new online portal designed for learning, sharing and discussing all things source code analysis.

    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 »
  • 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 »
  • Requiem for book-learnin’

    on Aug 26, 10 • by Alan Weekes • with 1 Comment

    Requiem for book-learnin’

    In the beginning was the word. And thanks to Guttenberg, the word was often enclosed in a glossy book and sold for $49.95 at my local computer store. The noble computer book with a shelf-life of six months was the perfect solution for a piano with a missing wheel. Computer books (part of the discipline of book-learnin’) are an increasingly endangered species. Sales of computer books have been off by 8 to 10% year over year for a decade, a trend that shows no sign of slowing. Still, I miss old-school, printed computer books. It

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

    on Mar 2, 10 • by Patti Murphy • with 1 Comment

    Limping through agile: Part 2

    At the risk of sounding like a co-dependent, in this post I discuss coping mechanisms that a “big picture” technical  writer (say, like my friend Beulah) can use to adjust to working in the granular conditions of an agile environment. Don’t give up the big picture     When you work on a bunch of stories or tasks, it’s trees, trees, trees everywhere  you look and not a forest to be found.  This means that a nice concise how-to could be a long way off while you document myriad  features. My advice is to finish

    Read More »
Scroll to top