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.