Reading this post will waste about three minutes of your precious time. You have been warned.
There have already been many reports about the Technical Communication UK 2011 conference. Look here for a nice recap.
Last and least, here are my thoughts.
This has been my first tech comm conference, but definitely won't be the last. It was great to be locked for three days with like-minded people in a four-star hotel, especially because I am the only tech author at my workplace. If you think that my workplace is surrounded by several miles of countryside, you understand that I feel a bit lonely sometimes. I could do with some company.
What prompted this post was the final keynote by Ellis Pratt on the state of the profession. Fewer job openings, salaries that have barely increased over the last several years, and a general lack of younger practitioners. A grim outlook.
I moved from astronomy (not astrology, astronomy) to technical writing. I couldn't help but question my career choice. Did I study for years to get a spaceship, only to crash-land it on a dying planet? Did I join a profession that's going to become extinct way before I do?
I don't think that's the case. Rather, I landed on a changing planet. Powerful volcanoes, massive earthquakes, and life forms furiously evolving to keep up. A dangerous place to be, but an exciting one too.
This is a feeling I've been having for the entire conference. The recurrent discussions on how we should be called (writers, authors, communicators and so on...) are just one symptom of the changes we are trying to adapt to.
Many of us know that we need to adapt and evolve. That's already great news. We may manage to turn from dinosaurs into cute little furry things and survive whatever asteroid may fall on our profession.
Don't get me wrong: I love dinosaurs. They were hugely successful for a long time. But they did not evolve fast enough. Or maybe they did, and now we call them birds. It's a matter of taxonomy.
Anyway, I'm happy I joined this profession at a time of exciting and rapid changes like this. It makes me want to keep studying, learning and improving. To use another metaphor, I feel like a jester who has to come up with new jokes every day, otherwise the king will get bored and have him beheaded. It can be a bit stressful at times, but it makes you treasure every day.
Thanks for reading!
Thursday, 29 September 2011
Wednesday, 8 June 2011
The phantom community
A tech author in orbit, part two
Sorry everyone, this post is short, not very interesting and it took forever to write. Don't say I didn't warn you.
It took forever to write because I was busy writing other stuff for an Open University course. Now that's behind me and I don't foresee other courses until next year, for lack of money rather than lack of enthusiasm.
But I digress. In the last post I told you about my efforts to engage our community of users, which must have seemed pointless to you since I added that there is no community.
First of all, why is there no community?
We produce data analysis software for a specific space mission. Our user base is relatively small, fewer than a thousand users spread across the globe. All these users gravitate around specific projects. Expertise is shared within these projects. Data is proprietary and is jealously guarded. There are James Bond-esque tales of images leaked out of top secret meetings and used by rival teams to publish papers. No killings and kidnappings yet, but I'm sure it's just a matter of time.
These groups are competing against each other, and sharing knowledge is not in their interest. Not before they have published plenty of influential papers, anyway. If I shattered your romantic idea of science as a common undertaking of mankind, I do apologise.
The good news is that the situation is evolving. More and more data are becoming public, after their proprietary period expires. There are more and more new users not affiliated with any of the big groups. Eventually, all the data will be public, and it will take years to squeeze all the science out of them.
In other words, there will be a community. Even more if we succeed in adapting our software to other missions. We'd better be prepared for that.
Will our efforts of community building succeed? Watch this space to find out. Whatever the outcome, there will be valuable lessons to learn. Besides, tales of failure give readers that warm fuzzy I'm-so-glad-it-wasn't-me feeling.
Thank you for reading!
Sorry everyone, this post is short, not very interesting and it took forever to write. Don't say I didn't warn you.
It took forever to write because I was busy writing other stuff for an Open University course. Now that's behind me and I don't foresee other courses until next year, for lack of money rather than lack of enthusiasm.
But I digress. In the last post I told you about my efforts to engage our community of users, which must have seemed pointless to you since I added that there is no community.
First of all, why is there no community?
We produce data analysis software for a specific space mission. Our user base is relatively small, fewer than a thousand users spread across the globe. All these users gravitate around specific projects. Expertise is shared within these projects. Data is proprietary and is jealously guarded. There are James Bond-esque tales of images leaked out of top secret meetings and used by rival teams to publish papers. No killings and kidnappings yet, but I'm sure it's just a matter of time.
These groups are competing against each other, and sharing knowledge is not in their interest. Not before they have published plenty of influential papers, anyway. If I shattered your romantic idea of science as a common undertaking of mankind, I do apologise.
The good news is that the situation is evolving. More and more data are becoming public, after their proprietary period expires. There are more and more new users not affiliated with any of the big groups. Eventually, all the data will be public, and it will take years to squeeze all the science out of them.
In other words, there will be a community. Even more if we succeed in adapting our software to other missions. We'd better be prepared for that.
Will our efforts of community building succeed? Watch this space to find out. Whatever the outcome, there will be valuable lessons to learn. Besides, tales of failure give readers that warm fuzzy I'm-so-glad-it-wasn't-me feeling.
Thank you for reading!
Thursday, 7 April 2011
Shoot the gatekeeper!
A tech author in orbit, part one.
I work for a space consortium. We built a satellite, launched it, and are now getting data for astronomers to write papers and make discoveries. An environment most technical authors have never experienced, so I thought I'd blog a bit about it, to let you know what it's like.
Let's start with something I said at a recent workshop, where many new users had come to learn about our data analysis software.
"Gatekeepers should be taken to a wall and shot."
My words were accompanied by this slide:
A bit extreme, perhaps, but my talk was the last one before lunch, a time when the attention of any audience is traditionally all over the place. I also struggled to make myself heard above the roar of growling stomachs.
My point was that, until very recently, the documentation model of our project has been fully controlled by gatekeepers, who decided what got published and when.
My aim is to turn gatekeepers into supervisors. Users should be able to publish information freely, for instance as comments to online documentation, with supervisors there to organise, tidy up and remove inappropriate content. Like this:
I'm trying to move gradually from one model to the other:
In a way, that's precisely what happened.
Space missions use old technology, as much as that seems surprising. First, because the technology must be tried and tested. Second, because a satellite takes years to develop, and one cannot keep replacing components whenever a new gadget hits the market. Once the satellite is launched, its technology is already comparatively old.
This "tried and tested" principle is also applied to the ground segment, that is, the hardware and software developed to process the data received from the satellite. The idea is "we'll adopt a tool only if we are reasonably sure that it will still be supported in fifteen years' time". This means being very conservative. For example, it was not trivial to persuade everyone that Java is not a passing fad, and that Fortran 77 really is past its prime.
Our bespoke help system, conceived many years ago, now badly needs to evolve and integrate with other tools, to allow more community interaction. Any of our users can easily update the Wikipedia page about our satellite, but they have no way to quickly flag inaccuracies on our documentation pages. A bit embarrassing, isn't it?
But technology is only part of the issue. Once we empower the community, we need the community to use this power.
And here's the problem. There is no community.
Curious? More on this in the next post...
I work for a space consortium. We built a satellite, launched it, and are now getting data for astronomers to write papers and make discoveries. An environment most technical authors have never experienced, so I thought I'd blog a bit about it, to let you know what it's like.
Let's start with something I said at a recent workshop, where many new users had come to learn about our data analysis software.
"Gatekeepers should be taken to a wall and shot."
My words were accompanied by this slide:
A bit extreme, perhaps, but my talk was the last one before lunch, a time when the attention of any audience is traditionally all over the place. I also struggled to make myself heard above the roar of growling stomachs.
My point was that, until very recently, the documentation model of our project has been fully controlled by gatekeepers, who decided what got published and when.
My aim is to turn gatekeepers into supervisors. Users should be able to publish information freely, for instance as comments to online documentation, with supervisors there to organise, tidy up and remove inappropriate content. Like this:
I'm trying to move gradually from one model to the other:
- Opening up portions of our Wiki, which is still largely for internal use only.
- Establishing a presence on social media outlets such as YouTube and Twitter.
- Pushing for our bespoke help system to be updated to accept comments from users.
In a way, that's precisely what happened.
Space missions use old technology, as much as that seems surprising. First, because the technology must be tried and tested. Second, because a satellite takes years to develop, and one cannot keep replacing components whenever a new gadget hits the market. Once the satellite is launched, its technology is already comparatively old.
This "tried and tested" principle is also applied to the ground segment, that is, the hardware and software developed to process the data received from the satellite. The idea is "we'll adopt a tool only if we are reasonably sure that it will still be supported in fifteen years' time". This means being very conservative. For example, it was not trivial to persuade everyone that Java is not a passing fad, and that Fortran 77 really is past its prime.
Our bespoke help system, conceived many years ago, now badly needs to evolve and integrate with other tools, to allow more community interaction. Any of our users can easily update the Wikipedia page about our satellite, but they have no way to quickly flag inaccuracies on our documentation pages. A bit embarrassing, isn't it?
But technology is only part of the issue. Once we empower the community, we need the community to use this power.
And here's the problem. There is no community.
Curious? More on this in the next post...
Sunday, 20 March 2011
Open source desktop publishing
Desktop publishing is all about placing things on a page and moving them around: text, images, lines, boxes and such. You may think that technical authors wishing to do that should have their hands chopped off and their eyes plucked out. After all, shouldn't we only care about the structure of our documents and delegate presentation details to whatever tool we are using?
True, but there are cases in which tweaking presentation details is not a capital sin:
You may consider Scribus, an open source application available for Windows, Linux and Mac, and mature enough to produce professional-looking results. Scribus needs another open source package, Ghostscript, to export to PostScript and PDF formats. Once you have installed both, you are good to go.
I have recently put together an eight-page booklet about my project's help system, to be handed out at a workshop with many new users. It did not take a tremendous amount of effort, considering that I was new to Scribus. If you are too, you may want to start with the tutorial. If you are familiar with Adobe InDesign, keep following this blog: I will be describing in a series of short(ish) posts where the main features of InDesign can be found in Scribus.
Have fun!
True, but there are cases in which tweaking presentation details is not a capital sin:
- Quick reference guides. Usually that means a lot information to be arranged into comparatively little space. Having total control on every nook and cranny on the page may actually be useful (not to mention the intoxicating feeling of unlimited power).
- Training materials. You may want to develop some highly visual training guides, like the Head First book series.
- Marketing materials. With technical authors having to wear many hats nowadays, you may be asked to write some promotional material and "make it pretty".
You may consider Scribus, an open source application available for Windows, Linux and Mac, and mature enough to produce professional-looking results. Scribus needs another open source package, Ghostscript, to export to PostScript and PDF formats. Once you have installed both, you are good to go.
I have recently put together an eight-page booklet about my project's help system, to be handed out at a workshop with many new users. It did not take a tremendous amount of effort, considering that I was new to Scribus. If you are too, you may want to start with the tutorial. If you are familiar with Adobe InDesign, keep following this blog: I will be describing in a series of short(ish) posts where the main features of InDesign can be found in Scribus.
Have fun!
Sunday, 6 March 2011
Five tips for undercover tech authors
Hello there. I'm an undercover technical author. I'm telling you because I trust you won't give away my secret.
Anyway, not much of a secret, really. At my workplace, everybody knows that I do documentation full-time, and they appreciate my work, I think. Unless they are just being polite.
Yet my official job title is software developer, despite the fact that I have developed very little software since taking up this position. The point is that the idea of people doing documentation full-time is not part of the culture of my project. More on this in a future post.
If you are working undercover like me, read on. Perhaps your organisation does not contemplate full-time tech authors, yet documentation gets produced, mainly by you. Perhaps you started in another role but are taking up more and more documentation duties, and would like to make it your career. Perhaps you had to choose between a different job title and no job title at all.
It can be frustrating and disheartening at times, but it does not have to be. Here are five tips for you:
Thank you for reading. Are you, or have you been, an undercover tech author? Any other tips you want to share?
* To any outraged support staff who happen to be reading: that wast just a lame joke, please don't take it personally.
Anyway, not much of a secret, really. At my workplace, everybody knows that I do documentation full-time, and they appreciate my work, I think. Unless they are just being polite.
Yet my official job title is software developer, despite the fact that I have developed very little software since taking up this position. The point is that the idea of people doing documentation full-time is not part of the culture of my project. More on this in a future post.
If you are working undercover like me, read on. Perhaps your organisation does not contemplate full-time tech authors, yet documentation gets produced, mainly by you. Perhaps you started in another role but are taking up more and more documentation duties, and would like to make it your career. Perhaps you had to choose between a different job title and no job title at all.
It can be frustrating and disheartening at times, but it does not have to be. Here are five tips for you:
- Call yourself technical writer, technical author, or documentation engineer if you really want to brag. On your business card, LinkedIn profile, email signature, everywhere. Because that's what you are. The employment contract does not matter, the employment contract was overtaken by events.
- Invest in education and training. That's true for any professional in any role, of course, but as an undercover tech writer you might have trouble convincing your line manager to pay for "our" kind of training. If you can't, invest your own money. I said invest, not spend. You'd like to spend all your money on holidays, food and booze, but you invest part of it in the reasonable hope to get back more at some point in the future. The same holds for investing in training and education. You'll get back your money as a higher future salary, or as intangible benefits such as a job you love. Of course, as with any investment, do your homework before parting with substantial wads of cash.
- Consider joining a professional association. I know, more money out of your wallet. But I dare say even the psychological benefits of feeling part of a community should not be overlooked. Moreover, joining an association shows prospective employers that you take your job seriously.
- Open a blog, a Twitter account and a LinkedIn account, to begin with. Follow blogs and Twitter accounts of other tech authors. Leave comments, join discussions. Some would argue that doing so gives you all the advantages of joining a professional association, for free. I'll let you decide for yourself by weighing costs and benefits. Even if nobody reads your blog at first, do not give up. It is your growing repository of writing samples, ready to be shown to whoever may be interested in your services. Just keep it separate from any personal blog of yours.
- Campaign for the importance of tech authors. I don't want you to wear placards or chain yourself to the entrance gate of your company. Campaign with the quality of your work: let management see numbers that demonstrate how you made a difference. The key here is measurement: if you say "Everybody thinks my doc reads nice", you won't make much of an impression. If you say "Support calls decreased by 75%, feel free to lay off most of the support department"*, they will realise why tech authors matter. Just saying.
Thank you for reading. Are you, or have you been, an undercover tech author? Any other tips you want to share?
* To any outraged support staff who happen to be reading: that wast just a lame joke, please don't take it personally.
Monday, 28 February 2011
Stars on the red carpet
In my last post I wrote about covering free and open source tools for technical authors. But where to start from?
Applications came in, auditions were held, and the first list of winners is now out.
A convoy of limousines pulls up, fans go wild, paparazzi jostle for position. Here they come:
That's all for today. Stay tuned for the first episode of the Rants'n'Rambles series!
Applications came in, auditions were held, and the first list of winners is now out.
A convoy of limousines pulls up, fans go wild, paparazzi jostle for position. Here they come:
- GIMP, the GNU Image Manipulation Program, one of the most venerable and well-known open source applications out there. Aiming to be a replacement for Adobe Photoshop, it is not quite there yet, but already offers an impressive range of tools.
- Scribus, a page layout application battling it out against Adobe InDesign. Mature enough to be used for professional projects.
- Inkscape, a vector drawing application, Adobe Illustrator's nemesis.
- LibreOffice. A fork of OpenOffice with some interesting additional features.
- The cohort of wiki systems, among which TWiki is the one I'm most familiar with.
- Audacity, a digital audio editor to give that extra sparkle to your audio tracks for podcasts and screencasts. Competing against Adobe Soundbooth.
- Synfig Studio, a 2D vector animation program. Use it to add special effects to your screencasts and e-learning projects. Competing against Adobe Flash.
- LaTeX, a venerable typesetting system still stubbornly holding onto the world of scientific publications, especially in the physical sciences. It excels at rendering math formulas.
- Of course I haven't forgotten about DocBook and DITA, and all the free tools surrounding these standards. But so much has already been written for technical authors about these tools that I can't think of anything original to add (although I'm open to suggestions).
That's all for today. Stay tuned for the first episode of the Rants'n'Rambles series!
Sunday, 20 February 2011
What to expect from this blog
Not much I'm afraid. But here is what I have to contribute.
When I decided to revive this blog, I thought about what I could offer of value to potential readers. Something more than the usual rants and rambles.
After an embarrassingly long time, it hit me. For most of my career I've had to make do with a laughably tiny budget for purchasing the tools of the trade, but that is not at all uncommon, especially in this economic climate.
I have also been working on an operating system that, let's put it like this, has not been the main focus of many software houses. Perhaps that is relatively uncommon.
Working on Linux meant that I had to find alternatives to Photoshop, Camtasia Studio, Snagit, Captivate and many other tools commonly used by technical authors. I learnt a lot in the process, and I thought I could share it.
The good news is that there are alternatives to these packages, and many of them are pretty good and completely free, even for commercial use. Some of them are available not just for Linux, but also for Windows and Mac.
Expect posts on free and open source tools and comparisons with their commercial counterparts. Perhaps you'll discover some hidden gem, and react with a smug smirk to the next round of budget cuts in your company.
More details in the next post. Stay tuned!
P.S.: Of course you will also find a selection of rants and rambles, but I promise they'll be clearly labelled as such.
When I decided to revive this blog, I thought about what I could offer of value to potential readers. Something more than the usual rants and rambles.
After an embarrassingly long time, it hit me. For most of my career I've had to make do with a laughably tiny budget for purchasing the tools of the trade, but that is not at all uncommon, especially in this economic climate.
I have also been working on an operating system that, let's put it like this, has not been the main focus of many software houses. Perhaps that is relatively uncommon.
Working on Linux meant that I had to find alternatives to Photoshop, Camtasia Studio, Snagit, Captivate and many other tools commonly used by technical authors. I learnt a lot in the process, and I thought I could share it.
The good news is that there are alternatives to these packages, and many of them are pretty good and completely free, even for commercial use. Some of them are available not just for Linux, but also for Windows and Mac.
Expect posts on free and open source tools and comparisons with their commercial counterparts. Perhaps you'll discover some hidden gem, and react with a smug smirk to the next round of budget cuts in your company.
More details in the next post. Stay tuned!
P.S.: Of course you will also find a selection of rants and rambles, but I promise they'll be clearly labelled as such.
Subscribe to:
Posts (Atom)