We are looking for 2 tech writers for financial software in Copenhagen, Denmark:
- 1 Senior Technical Writer with at least 5 years experience
- 1 Technical Writer, graduates welcome
We are looking for 2 tech writers for financial software in Copenhagen, Denmark:
If you’re attending the tekom conference in Wiesbaden, consider joining me for my updated presentation “Getting ahead as a lone writer” on October 19 at 8:45 a.m. in room 12C as part of tekom’s international, English-speaking tcworld conference.
My presentation will be an updated version of the session I did at TCUK 10. I will talk about how to overcome neglect and raise your profile by running your job (more) like a business with best practices. Here’s the abstract:
Lone writers are often the only person in the company who creates and maintains documentation. They often operate without a dedicated budget or specific managerial guidance. In this presentation, Kai Weber will draw on his experience to show lone writers how to make the most of this “benign neglect”:
- How you can still develop your skills – and your career
- How you can raise your profile with management and colleagues
- How you can contribute to a corporate communication strategy
- How you can help your company to turn documentation from a cost center into an asset
Join us on Wednesday at 9:35 am on the upper floor in the foyer in front of rooms 12C and D for a #techcomm meetup after the session! @rimo1012 and I, @techwriterkai, are presenting at the same time in adjacent rooms, so if you know us from twitter, stop by and say hi!
I’ll be blogging from the conference, so watch this space…
In a typical day of my working life, writing takes a backseat to collaboration and communications. – This article first appeared as an “A day in the life” column in ISTC’s Communicator in the Spring 2011 issue, page 58. I really enjoy the “A day in the life” pieces, because they’re like chatting with fellow tech writers about their day at the office. So I was honored and proud to write one of the instalments, and I hope you enjoy it.
It’s an ordinary spring day, and I wake up in Frankfurt, Germany. When I’m lucky, the sun shines into my apartment to greet me. My morning routine is woefully brief, and I take a train to Bad Homburg shortly before 8am. The commute is pleasant since I live in the city, but work in the suburbs.
I arrive at the office around 8:30am. I’m the only full-time writer in the German office, though a tester across the hall writes part-time. Ten writers are based in Copenhagen and Kiev.
I start up the PC and get a cup of tea. I receive an email from a colleague who has found an error in the online help. I check with the developer; my colleague is right. I check it against the Release Notes. This is embarrassing, they contain the same mistake, nobody had caught it. The Release Notes have gone out already, but at least I can correct the online help for the next release.
Next, I check the Solutions database, which is what we call our FAQ collection. We technical writers are responsible for editing the entries and aligning them with our documentation. A consultant has created an entry with a workaround. That’s odd: the Solutions entry does the trick, but we should really just fix that exception! I consult with the developer who will fix the bug. We will publish the Solutions entry for the time being and delete it in the next release.
It’s 9:30am, and my testing colleague asks for my opinion. She is about to finish her first manual and has created a list of index terms and wants my opinion on them. Also, the Word template for manuals has become corrupted somehow, so we need to fix the page headers, which are supposed to show chapter numbers, chapter headings and page numbers. Her index looks good, so we agree on it very quickly. Then we wrestle with Word for a while.
At 10am, it’s time for a video conference with the Copenhagen headquarters. I’m one of four people developing the future documentation strategy. We’ve already sketched out the processes on how we want to work in the future to implement structured and topic-based authoring.
Today, we discuss a design for an information model that I’ve drafted. I’ve basically taken a subset of DITA 1.1 and mapped its topic types and elements to our documentation contents. My colleagues have been reviewing it before the meeting, and they point out some parts that are inconsistent or confusing. Also, our model is still missing a couple of metatags, which means that my task until our next meeting will be to clarify some sections and to add the metatags. The video conference ends at noon, so I can catch my German colleagues as they head down to the cafeteria for lunch.
After lunch, I find an email by a colleague writer. I’ve agreed to review his manual, and here it is. The review is tricky since I don’t know a lot about the module he describes. SimCorp Dimension is a fairly large and complex wall-to-wall system, so not every writer knows all modules in detail.
We had agreed that he’ll need another reviewer for the actual contents, but I can still help him with the chunking of topics and the manual structure. I propose to change the nesting of topics in a couple of places. Also, the topic headings aren’t fully consistent yet. I hope he will find my suggestions helpful.
Reviewing the manual reminds me that I still need to find reviewers for my own manual that is just about finished. I can always count on the product manager (if he can find the time), but I like to have one of the implementation consultants review it as well. They know our customers and their workflows best from implementing the product on site, so their reality checks are invaluable.
At the same time, it’s often tricky to find someone who can spend one or two days away from a project. It helps that they find the manuals generally useful. I approach the team leader and tell him when the manual will be ready and that it will take 6 to 8 hours to review. He has a couple of colleagues in mind, but needs to check their schedules. He will get back to me.
It’s 3pm, and I start to actually write documentation. I continue to write Release Notes for the upcoming release. That means I go through all the development efforts in the tracking system and briefly document the enhancements and their benefits.
In between, I come across one enhancement where it is not clear yet whether it will actually be included in the upcoming release. I contact product management and, indeed, it’s not been decided yet. That makes me nervous: in the previous release, some of these decisions came awfully late and required some last-minute editing.
Though I started writing rather late, I make some good progress. Around 5pm, I call it a day and take the train home. When I’m lucky, I can see Frankfurt’s skyscrapers shimmer silver in the setting spring sun.
How much time to do you spend writing, as opposed to communicating? Is this similar to what your days look like? Feel free to leave a comment.
I think this year’s megatrend for technical communicators and their managers, especially employed ones, is to position tech comm as a business in its own right – or to be redundant in the long run.
This is my conclusion after thinking about three astute predictions that Sarah O’Keefe recently blogged about.
- I know: I’m late to the predictions party. And I’m actually not very good at crystal ball gazing. I’m much better at reconfiguring what I find. So my contributions are comments and some additional reasons why I think Sarah’s right.
If you’ve read Sarah’s post, I’ll just remind you of the headings of her predictions:
If that doesn’t ring a bell, head on over and read her post, I’ll wait…
I think Sarah’s predictions are really three sides (?) of the same coin. And I’d be surprised to see a documentation team experience only one of them.
The lackluster attitude about documentation of “No one reads it, but you gotta have it” has been widely replaced by close scrutiny of its value add and ROI. I’ve recently seen a doc team’s initiative that had to present the same business case, including cost saved and break even, as any other internal initiative that wanted to spend some money. But more is at stake for us writers than playing the numbers game with managers and bean counters.
The question is how the tech comm team is perceived: As a cost center or as contributing to the corporate assets. The latter is of course more desirable and can only succeed when we break down departmental silos, when collaborate with other teams and become user advocates, see my earlier comment on Scriptorium’s blog.
Now take a step back and think of what that cost vs. asset question means to your job and your career outlook. To me, it’s awfully close to being seen as part of the problem or part of the solution…
Another reason why I think tech writers do well to consider and promote their business value is…
Sarah’s second prediction follows directly from attention to business value: Once a company expects ROI from documentation, it will want to monitor the output. And that means to hold the documentation team accountable, not by measuring the quantity of produced stuff, but by measuring the quality of useful assets that have been efficiently produced. (It’ s worth keeping in mind the difference between accountability and responsibility; link courtesy of Jurgen Appelo and his presentation on authority and delegation.)
In the metrics, you may have some leverage: If you’ve ever tried it, you’ll find it’s awfully hard to come up with reliable metrics for documentation quality. The good news is that your managers will usually find it even harder. That’s a chance for you to apply some “Top strategies to embrace cost metrics” .
If you’re alert and on top of your game, you’ll find you have some agency in how you’re measured. It won’t always be your choice alone, but to a certain extent, you can choose sides in…
The distinction looks crude, but I’ve found that many technical writers fall into one of the two camps that Sarah has identified:
Note that this distinction has nothing to do with quality! I know very diligent, highly qualified people in both groups, and I’ve seen sloppy work in conventional manuals and modern screencasts.
I believe how that schism plays out for each writer in a team has a lot to do with the accountability of the documentation team, the responsibility of the team members and the dynamics between the members: Ideally, both types complement each other – and can show management that they are strong and agile because of their complementary strengths.
Okay, so treating your documentation as a business before everybody else does sounds reasonable. For specific next steps, may I recommend the slides from my TCUK presentation “Getting ahead as a lone writer” and my other blog posts for lone writers. Even if you’re not a lone writer, you’ll find many ideas also apply to documentation teams.
What do you think? Are these trends part of a larger movement to economize and commodify technical writing? Or is it nothing new, not worth beating a dead horse over? Please leave a comment.
An index is an important navigation device in documentation, especially in print. It helps users to quickly find key terms, concepts, functions, and instructions.
To make your index entries helpful, anticipate user searches. Think of it as a parallel to online search results. When building an index, think primarily of what users might want to look up and find in your documentation.
To create an index, follow these three steps:
When creating index entries, consider these issues:
At any time after creating your first index entries, create and preview your index, depending on your help-authoring tool or other software.
After you have created all index entries, rebuild and update your index. Then review the existing index for inconsistencies and go back to the index marks in the text to correct the following issues:
Optimal length and scope of an index is the result of a compromise: Make your index as long as necessary to support readers to use your documentation quickly and efficiently. And make your index as short as possible to spare yourself unnecessary work and the reader confusion.
Whether your index is too long or too short is a matter of judgement. Put yourself into the reader’s shoes once more and review your index. You may find that your index is a little too short and missing some terms that users might also look up.
Good resources for building an index are these two web pages and three books:
Please help me out by weighing in with your experiences and opinions to the questions above. Or feel free to tell me if I forgot anything? How do you create an index for printed documentation? Should online help also have one, or is the search enough? Please leave a comment.
Moving to a structured writing environment can change the metrics of documentation. That’s one of the lessons I learned in a great webinar by Scriptorium‘s Sarah O’Keefe about “Managing in an XML environment”.
If you’ve missed it, check out the 45-minute recording/slideshow on their website. You’ll find it very interesting, if you’re wondering what it will be like to create and maintain documentation, once you have implemented XML. I’ll summarize a few aspects that I found interesting and comment on them.
Creating documentation in an XML environment increases the transparency in writing documentation, for better or worse. Tech writers’ work in XML is more visible earlier in the process: Without XML, a writer may deliver a print-ready PDF after months. With XML, she might check in topics every day for a nightly build.
Just as content gets chunked from books to topics, so progress gets chunked from weeks and months to hours and days. What can be measured often will get measured, so Sarah warns: Beware of seductive metrics. Measuring pages per day, for example, is silly: It will increase page count, but not necessarily the quality or the effectiveness of the documentation.
Measure something useful instead. Sarah suggests the QUACK quotient:
(quality + usability + accuracy + completeness + “konciseness”) / cost
Sarah goes on to define each of the five “QUACK” factors in similar terms as Gretchen Hargis, et al. in Developing Quality Technical Information. For example, quality considers whether the documentation is well-written and well-structured. “Konciseness” (spelling follows acronym as form follows function) means to provide as little documentation as is necessary, but no less. This improves efficiency for users and localizers alike.
I think this approach is great for scenarios where you can’t get out of cost metrics. Using accepted quality criteria is definitely better than being held to junky metrics.
But I wonder how quantifiable the five dividends actually are: How accurate is a topic? “Very accurate”, if I’m lucky – but I wouldn’t know how to put a number on that… Also, each dividend should be weighted according to audience and industry, Sarah explains. For example, completeness of documentation is more important in regulated industries than video games. That doesn’t make the quantification any easier or less contested.
My own strategy requires even more leverage for tech writers than just pushing a new formula through to assess our work. So it probably doesn’t work for all tech writers.
The QUACK quotient takes for granted that documentation is a cost center. Of course, many managers share that view. But I wonder if we tech writers wouldn’t be better off, if we got out of that defensive corner altogether.
I think it helps us more in the long run to show how documentation contributes to the larger corporate processes of production and value added. So I suggest that it’s worth to argue along these lines:
If you’re into DITA or want to see how cost metrics for structured writing break down to actual numbers, check out Mark Lewis’ clear and thorough white paper “DITA Metrics: Cost Metrics“:
You’ve already concluded that moving to DITA will save you tons of time and money. But management says prove it. This paper helps you determine the cost portion of the ROI calculation. What are my costs now? What will my new costs be with DITA? And what is the difference—my savings?
What do you think is the best way to justify tech writing cost? What scenarios or strategies have you seen succeed or fail? Share your thoughts in the comments.
Today, I’m re-posting a piece that I first published on April 23, 2009, on the now defunct Content Wrangler site and then moved it to this blog as legacy material that was buried in the dark links of history…
I’m revisiting that post for two reasons: To my surprise, this has been one of my most popular posts in terms of search queries, so apparently this is an interesting topic. And I’ve discovered an additional argument with a twist that was new to me…
But first, let’s rewind…
Last year, I wrote:
How do you argue for the preference of ragged-right over justified alignment in print? Searching the web, I soon came across pages which mentioned research, but it was harder to actually find it.
Now I’ve found more arguments:
Karen Schriver’s book Dynamics in Document Design of 1997 is both comprehensive and excellent in explaining the motivation, the tools and the history of good document design. Be warned, however, that it deals almost exclusively with printed document design. Online design is the afterthought that takes up Appendix C, pages 506-517. (That detail right there tells you pretty much what kind of a book it is… )
Schriver essentially argues that ragged-right vs. justified is the wrong question – imposed on us by software options, I want to add. According to Schriver, the real issue is word spacing.
Regular word spacing makes for faster reading and more accurate comprehension, in both ragged-right and justified text. Much of the software we use for writing gets word spacing in ragged-right alignment reasonably right without too much trouble. The problem with justified text is that it requires a sophisticated balance of letterspacing, word spacing and word hyphenation which much software apparently doesn’t get right automatically. Instead, it…
…creates a disturbing visual illusion known as “rivers” – paths running vertically through the text that connect the blank spaces between words on adjacent lines. (p. 270)
Here’s an illustration of rivers, from the Wikipedia article on Sentence spacing:
So, the bottom line is: If you have rivers in your text, consider ragged-right alignment to do your readers a favor – or invest extra time in spacing your lines nicely.
- If you know of any other arguments or sources that can help us tech writers with alignment and justification, please leave a comment!
Tech writers don’t just write, we frequently also edit what our peers have written. As Tom Johnson recently tweeted:
Can’t decide if the technical editor role is dead or if technical writers have evolved into this role as their new default. 8:40 AM Apr 23rd
I wouldn’t call it a “default role” for us writers, though the “pervasive idea in companies that ‘anyone can write’” creates more demand for this role (paraphrased from another tweet by Tom three hours later).
I’ll gladly edit the work of another tech writer (and rely on their feedback in return), but I’m less likely to “clean this up by noon”: I’m not grammar boy, and if anyone can write, then anyone can also clean up behind himself… If and how I edit depends on the situation. But what do I mean by editing?
(And what do I mean by that photo? Nothing in particular. Except maybe: How do you illustrate editing? )
When it comes to technical editing I have three heroes: Robert Van Buren, Mary Fran Buehler, and Jean Weber. Robert and Mary put together the ultimate tech editing guide back in 1980, called Levels of Edit. An STC edition from 1992 is apparently out of print, but there’s still a summary and a PDF version out there. Their booklet is the most comprehensive and best structured guide to tech editing that I know. They distinguish nine (!) types of edit:
Depending on how thorough your task and how much time you have, you go through all or only some of the levels. In fact, they suggest five different levels of edit for different purposes of a document. Unless you create a production edit for a printing house or publisher, you will probably omit types 1 and 5. The others may be more or less relevant, depending on general policies and what kind of document you’re editing.
I find the nine types of edit so clear and well-structured, because they help me to stay consistent and focused in my editing:
Yes, it does mean that I go through the same document repeatedly, but I find that the additional time spent scrolling or turning pages is made up by the better focus.
You can edit your own work, but I don’t recommend it: I find I’m too entangled in my writing, constantly tempted to fix an odd phrase here, a less than perfect table there. If at all feasible, have your work edited by someone else, and edit the work of colleagues.
This is where my third hero Jean Weber comes in (no relation to me): Jean knows all about how to work with editors – or, if you’re an editor, how to work with people who write. She also pointed me towards Levels of Edit.
Jean is in Australia and, according to her website, retired from paid work. But she’s so generous, she shares her knowledge and experience. I found three articles especially helpful:
How do you edit? How are your documents edited? Do you edit your own work or someone else’s? Feel free to share issues and insights in the comments.