Archive for the ‘Documentation’ Category

  • 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 »
  • 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 »
  • 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 »
  • RTFW

    on Dec 15, 09 • by Helen Abbott • with 1 Comment

    RTFW

    Our new documentation wiki is up and running! For awhile it seemed like we’d never do it. We have a team white board that records our panic level, and for several weeks, the level was up around “hysterical” and “wanting to open my own daycare”. We also have a white board in front of the doc area, in a hallway where everyone walks by to get to the kitchen.  At one point when we were particularly frustrated with MediaWiki, the topic was “names for the new doc wiki”. A few good suggestions: Duh-Wiki Kwiki Wooki

    Read More »
  • “Okay. I’m in Costa Rica. Now what?”

    on Sep 3, 09 • by Patti Murphy • with 3 Comments

    “Okay. I’m in Costa Rica. Now what?”

    “Now what?” is that uncharted territory between “Getting Started” product guides and the challenge of incorporating a new tool into day-to-day activities. In fact, I’m convinced that “Now what?” is one of many creatures inferred by the “Here be monsters” legend inscribed on uncharted regions of old nautical maps. I think of it like this: You buy an exciting adventure package to Costa Rica. You put your money down. The tour operator hands you a map. And then you end up…in Holland. Time to call your emergency number: You: “Can you help me out?

    Read More »
Scroll to top