Archive for the ‘Free Software’ Category

Nine months ago, Linux.com stopped publishing. Four months later, the announcement came that its web address had been bought by the Linux Foundation. The change wasn’t the end of independent news about the free and open source software (FOSS)community, but it has left a gap that is still unfilled. And, although as a ex-stringer for Linux.com, my bias is obvious, I can’t help thinking that the community is poorer for it.

Don’t get me wrong: Under the Linux Foundation, Linux.com is far more of a community site than the old version ever was, and often more imaginative, too. I’ve written the occasional article for the new version of the site, and hope to write more for it in the future. But the Linux Foundation has never pretended to be interested in a news site, and it runs far more how-tos than news stories. When it does run news, it tends to mention the bare facts, and add some off-the-cuff commentary. The new site simply has different priorities from the old.

Other news sites exist, but many of them appear to be limping along on starvation budgets. Most stories on Linux Planet and Linux Today are recycled, with the exception of editorials and blog entries by editor Carl Schroder. Datamation and Linux Pro Magazine publish only a few new stories online each week. The Heise publishes more, but is spotty in its coverage, and rarely has stories of more than five hundred words. The most consistent producer of new stories is LWN, and its stories are handicapped by the fact that the site publishes its main edition weekly, which means that its in-depth coverage tends to be confined to ongoing rather than breaking news.

Possibly, I’ve missed one or two sites. Also, some blogs or planets provide news and insightful commentary in their own limited subject matter. Yet the fact remains: the FOSS community has less independent news than it had a year ago.

No doubt some people in the community are hardly aware of the fact. They are busy with their own projects and jobs, and have only a passing interest in what is happening in the rest of the community. Still, from the countless comments I’ve had from people who assume that I’ve disappeared, the old Linux.com was where much of the community went to be informed, and they haven’t moved to the other news sites (if they had, they would know where I’ve been, because I’ve written for most of the other sites in the last nine months).

This lack of news concerns me – and not just as a writer who might benefit if the situation changed. The FOSS community is a complex, quickly changing place, and reliable sources of information can help it to function. Although news sites cannot cover everything, and their selection of what to cover may mean that some events are omitted or under-emphasized, they make the effort of keeping informed much easier for each of their readers. Without news sites, keeping informed requires much more effort. In effect, the sites make the effort for all their readers.

Nor is that a bad thing, so long as the sites make good faith efforts to be thorough and uphold journalistic integrity. If they sometimes make mistakes, they will also publish followups. If they publish a commentary expressing one side of a controversial subject, the next week they may publish another commentary that gives the other side. Although individual articles may fail to meet the highest standards, the overall result of having news site is a better informed community – and an informed community, of course, is essential for the proper functioning of a democratic, grassroots organization like FOSS.

Theoretically, blogs could fill the current gap in news sites. And, in practice, that is where many community members are probably turning. But, while I have nothing against blogs (obviously, or I wouldn’t be writing one), they are only a partial substitute for a news site with journalistic standards.

Blogs can announce news, and comment on it. However, with few exceptions, their writers are less likely than journalists to investigate news, or attempt to balance their sources. Most blogs tend to be short on detail, and to miss nuance. All too easily, they serve to repeat rumors and half-truths that a journalist is more likely to investigate and debunk as necessary. Few bloggers even attempt to uphold journalistic standards, which means that you frequently have to be familiar with the blogger’s previous works before knowing if they are a trustworthy source of information. As flawed as journalism often is, at its best, it holds to higher standards than bloggers and is more reliable overall.

As both a reader and a journalist, I would like to see the gap in FOSS news site filled. The question is, how is that possible? So long as they are under budgetary restraints, the remnant news sites are unlikely to increase their coverage. A group of writers might start a new site, but they would need to have other income while they built audience and revenue. Could an investor or a philanthropist help without compromising the independence of a new site?

The question has no easy answer. However, the more I think about it, the more I am convinced that finding any answer is important.

Read Full Post »

The other evening, we received a call from someone we knew fifteen years ago. We hadn’t heard from him for several years, and, while we had nothing particular against him, we were content to drift out of touch. But there he was, a disembodied voice bringing up names that these days we hardly thought of from one year to the next, and urging that we should get back in touch with people with whom we no longer had anything in common. The experience was sad and guilt-provoking in equal measure. At the same time, I resented it, because our caller believed he still had the right to make demands on us.

All in all, it was a perfect example of what American fantasist Harlan Ellison once called taking a tour through his life. He meant, as you can probably figure out, somebody leaping to conclusions about how he thought or felt, then acting upon them rather than responding to what he actually said or did.

I don’t have one-fortieth of the name recognition that Ellison had in his heyday, but as a writer who publishes mostly online, I have people taking tours through my life all the time. They miss the sarcasm, take a phrase out of context, or misread, and then they take me to task for what they imagine I said or believe.

For example, once when I did a brief commentary in which I suggested that a woman-only distribution of GNU/Linux might be worth trying. Among other things, I wrote, “I’m not a great believer in the idea that women are less aggressive than or interact differently from men. Yet even I have to admit that most of the regulars on free software mailing lists for women are politer and more supportive than the average poster on general lists.” Then one of the commenters inferred that I must be single and a loner who knew nothing about women, because they obviously were different from men. He apparently stopped reading with the first sentence of the passage, and was willing to blast me on the basis of his incomplete understanding. Never mind that another five seconds’ reading might have prevented his mistake and public embarrassment.

As an ex-university teacher who tried to encourage careful and sympathetic reading among students, my first impulse is to correct such statements as politely as I can. However, experience has taught me that the effort is usually a waste of time. Nobody likes being proved wrong at the best of times, but, when they are also proved incompetent, most people become defensive and angry. I save everybody’s time and keep my blood pressure lower if I don’t respond, or, at the very most, stop the email exchange after my second message.

That probably leaves the commenter thinking that they’ve won, but I can live with that. I don’t know them, after all.

But some tourists through my life are not simply on a self-conducted tour, but trying to sell other people tickets as well. There’s only two or three of them, but they spend a surprising amount of time on their blogs and web sites attacking me for what I did or didn’t do, or for what they imagine I said.

Why they attack me in particular, I have no idea. Maybe it’s because I write online and seem accessible.

What disturbs me about these tour guides is not that they disagree with me. They have every right to do so. Occasionally, they even point out actual mistakes (although they frequently confuse the concepts of “mistake” and “different opinion”). It is not even their relentless anger (explicable to me only as too much caffeine and too little sleep), their refusal to follow even the basics of civilized discussion, or the question of why they don’t write about someone important.

Rather, what disturbs me is the cognitive dissonance that sets in when I read their comments about me or my articles. Possibly, they get carried away by their own rhetoric, but the image they present of me or my articles is so far from any possible perspective that I can’t even call it a distortion. I suspect they are projecting an image drawn from their own imagination or systematic misreadings and over-simplifications. A Microsoft shill or dupe? A writer who is one with Dan Lyons and Laura Didio? Considering that an even larger group of readers identify me as completely biased to the free software school of thought, these accusations would be laughable if only they were not so humorless and ill-natured.

Emotionally, what they say about me has no resonance whatsoever. It simply strikes me as bizaare.

When I first started receiving these attacks, I used to respond to them, thinking that I couldn’t let such outrageous comments stand unchallenged. But doing so, I quickly found, is an even bigger waste of time than responding to those on the self-guided tours. The tour-guides never give in.

For these reasons, I rarely read the tour-guides. The occasional pingback to my blog or a note from a friend tells me that they are still out there, but I mostly catch only snippets of their latest rants. I tell myself that to be known as someone attacked by such people is a mark of honor, and, considering their other targets in the free software community (many of whom I’ve met and liked, although not always agreed with), I should consider their attacks a sign of distinction, no matter how undeserved.

But increasingly, just as with the former friend who called, when I happen across the tour-guides, what echoes inside my head is Ellison’s reply to the similar people in his own life:

“I don’t know you, and you don’t know me.”

And I, for one, am very content to keep things that way.

Read Full Post »

I am just back from COSSFest, a free software event held in Calgary, Canada. You can read about the conference on my Linux Pro Magazine blog at:


Read Full Post »

I wrote for Linux.com for five years, so anything I say about the transfer of the site from SourceForge to the Linux Foundation is hopelessly biased. Still, while I wish the Linux Foundation every success with its new community-oriented version of the site and hope to do some writing for it, I am sorry to hear that the new site will not be focusing on journalism. The free and open source software (FOSS) community had something special in Linux.com, and many people don’t seem to recognize what’s been lost.

Quite simply, the old Linux.com site and its sister-site NewsForge were the largest source of original news in the FOSS community. That is not just bias, but objective fact. The FOSS community has other sources of original material (and I’m pleased to write for them), incuding Datamation, Linux Journal, and Linux Planet, but only LWN is in the same league as the old Linux.com’s average of four stories per day, plus one one two on weekends.

And these weren’t just links to other stories, or quick rewrites of news releases, the sort of content that you find on many technology sites. These were independently researched stories, ranging from breaking news and opinion pieces to how-tos and reviews, each averaging 800 to 1200 words.

Even more importantly, the quality of Linux.com stories was consistently high, thanks to the general policies of editor-in-chief Robin “roblimo” Miller and the copy editing skills of executive editor Lee Schlesinger and his various assistants over the years. Sometimes, a regular contributor slipped up, or a new one published a shoddy piece, or the submissions didn’t include enough pieces to maintain both the highest standards and the busy publishing schedule, but the overall quality surprisingly high (I’m talking about other people’s work here, you understand, and saying nothing one way or the other about my own).

Again, this statement is not just bias. If you don’t have time to re-read the archive (which I’m grateful to hear that the Linux Foundation will preserve), consider some of the people who wrote for Linux.com: Chris Preimesberger, who moved to eWeek; Joe “Zonker” Brockmeier, now community manager for openSUSE; Lisa Hoover, now a successful freelancer, or award-winning writer Joe Barr, who died at his workstation last summer.

And that list is just the start of a list of regulars that includes such writers as Nathan Willis, Dimitri Popov, Susan Linton, Ben Martin, Federico Kereki, and Marco Fioretti. Not every successful writer covering FOSS and technology had a stint at Linux.com – not by any means – but a surprising number did, and I think they were better for the experience and the consistent market for their work.

Both Robin and Lee might be embarrassed if I called Linux.com a center of excellence, but that’s what it was, and my own experience shows that. Virtually everything I know about journalism, I know from selling stories to Linux.com. I learned journalistic ethics from Robin and impartiality, pitching a story, and structure from interacting with Lee. I learned editorial writing from the example of Joe Barr, and how to cover breaking news by being given a chance to try it.

Five years ago, if anyone had told me that I would be writing and selling some twenty thousand words per month and surviving as a freelance writer, I wouldn’t have believed them. But, thanks largely to my experience at Linux.com, I do. Linux.com taught me so well that I have even managed to survive its end as a news site – sometimes less comfortably than I did when it was a going concern, and scrambling more as I write for half a dozen editors, but surviving all the same.

Some readers criticized Linux.com for not being blindly supportive of everything and everyone claiming the FOSS label, or for not sharing their opinions. Others mistook covering a topic for support of it. But what such readers failed to understand, and what made Linux.com important for the FOSS community was its honesty. You might disagree with what writers said on the site (I frequently did), but you could trust that they were giving an honest opinion, uninfluenced by advertisers, counter-opinions from editors, or even their general sympathies for FOSS. You could trust, too, that, except in obvious commentary, they were making a good faith effort at fairness (whether or not they achieved it), and not engaging in the demagoguery that passes for journalism on some other kinds of sites. This truth-oriented journalism is more important to a community than blind reinforcement of basic tenets, because it genuinely and reliably informs in the short run, and, in the long run, becomes a first draft of history.

I knew three months ago that Linux.com was being transferred to the Linux Foundation, but I have been under non-disclosure until now. In the mean time, I’ve moved on, writing for other sites and expanding my existing association with other sites. But, the news of the transfer brings the regret back to me, and I wonder if SourceForge ever knew the value of what it had.

Still, looking back, I’m proud to have been accepted as part of Linux.com, and to have learned the writing trade there. I couldn’t have asked for a better school in which to learn.

Read Full Post »

For a freelancer, complacency can mean loss of income. This is a lesson that freelancers can never hear too many times – and one that I apparently need repeated more than most. A few weeks after I blogged about how I had managed to replace the income I lost with the closing of Linux.com with other assignments, I found some of those assignments failing, and suddenly found myself scrambling to replace them.

Fortunately, the job-hunting skills I’d learned as a communications and marketing consultant soon paid off.

As before, basic survival wasn’t an issue. We had income for basic survival, and, since we own our townhouse and have never lived beyond our means, we had no worries about debt. All the same, the situation was disconcerting. I thought I’d solved the income problem.

The problem arose because of two clients. In the first case, the client had at first seemed willing to commit to two stories per week from me. However, after a few weeks, they confessed what I had already concluded from their actions: That they were unable or unwilling to take more than one story per week.

In the second cases, the editor forgot that they had agreed to take two stories from me in February, and budgeted the money instead for articles from other people. Since this was a short term arrangement, it wasn’t as important as the first one, but it was still the first time that an editor had reneged on me for any reason, so it came as a shock. For one thing, I rather liked the editor, and preferred to think well of them. For another, I had counted on having a month to figure out a replacement for that income. Coming on top of the other case and some personal bad news that I choose to keep private, it felt like one damned thing after another.

For a day or so, the situation got to me. I even went so far as to consider revising my resumes and looking for straight work. Despite the recession, the work for writers, editors, and instructors of my experience were plentiful in the Vancouver area, but it all seemed dull and routine compared to what I have accustomed to in the last four years.

Then common sense took me by the scruff of the neck. There were still plenty of outlets for free and open source software articles that I hadn’t got around to trying. I spent an afternoon on the Internet learning about the potential clients (something no freelancer or job-hunter should ever neglect), and prioritizing them according to how their needs compared with my areas of knowledge, the size of their audience (which is often found on pages for advertisers), and, where possible, how much they pay per article.

The next morning, I started phoning. I could have emailed, and my queries easier on my nerves, but, for serious business conversations, there’s still nothing as direct as a phone call. Hearing a voice is personal in a way that email or even chat isn’t, which makes a phone call a way to distinguish yourself from anyone else and have yourself remembered.

To my surprise, I appear to have been lucky the first time out. Details are still being worked out, but I expect to be doing an online blog and a print column, as well as contributing other articles.

You’ll have to imagine me dancing around my living room and pumping my fist in the air (or maybe you shouldn’t; it isn’t a pretty site).
But, while I’m glad of the respite, I hope I’ve learned my lesson. I can’t say that I don’t make the same mistake twice, but I hope to say that I won’t make it three times. I still have other a prioritized list of markets (something I should have readied a long time ago), and, if any other client disappears on me, I’m ready to find replacements.

Given the current economic conditions, I wouldn’t be surprised if I’ll have a use for that list again in the next few months. But, so far, I can still repeat what I said in my earlier post: Freelancers are better equipped to survive the recession than most – and should generally survive better.

Now, though, I would add: A few job-hunting skills don’t hurt, either.

Read Full Post »

I have interviewed Richard Stallman and other members of the Free Software Foundation often enough that he remembers my name (no small feat, I’m sure, considering the hundreds he meets each year). Once or twice, I think, in talking about parrots and folk music, I may have caught a personal glimpse of him. But, even if I haven’t, I generally support the Free Software Foundation. So, when Richard Stallman spoke the other night at the Maritime Labour Centre in Vancouver, I wasn’t going to see what he is really like, or to hear his arguments. I went to see his public persona, and to observe how other people reacted to it.

First, in case you are wondering, Stallman is neither three meters high, green-skinned, nor fanged like a sabertooth tiger. He is a man in his mid-fifties, surprisingly short –maybe 170 centimeters high– and apparently not given to exercise. His hair is long and graying, and so is his beard. Both are uncombed. His clothes are business-casual.

He was tired when he arrived at the hall, and perhaps feeling a little over-exposed to people, having given a speech earlier the same day at the University of British Columbia. After meeting the organizers, he immediately requested a quiet place to work. The request was probably a necessity, since Stallman keeps in close touch with the Free Software office in Boston, but I also suspect that he was relieved to have a moment to himself in the middle of a day in the public eye.

Another myth-buster: Stallman starts by being polite when you talk to him. Nor is he humorless. His comments sometimes show a wry sense of humor, often based on literal interpretations of other people’s phrases. He shows, too, an interest in dining as a social occasion, lamenting that, when he arrived the previous night, he had no one with whom to eat. And, after listening to the local band that warmed up the crowd for him with Flanders and Swann’s “The GNU Song,” he got up on stage to sing “The Free Software Song” with them, his smile not the least deterred by the fact that he is a mediocre singer and could only remember some of the words.

At the same time, Stallman is not always easy to talk to. He seems a little deaf, and impatient with the fact. He is impatient, too, when talk strays into an area where he has expressed the same opinion for decades – or perhaps he simply does not suffer fools gladly. And who can blame him? At this point in Stallman’s public career, anyone who calls him a supporter of open source software has clearly not been paying attention. Nor can it be easy to cover the same basic subjects dozens of times each year.

One on one, he might make some women uncomfortable with compliments about their attractiveness that are a little too quick and open by modern standards. Other women seem to find him chivalrous. Both sexes might accuse him of expecting to be the center of attention, but again, who can blame him? When he is on tour (and he is often on tour), he usually is the center of attention, with his hosts hovering nervously around him.

After our phone conversations, I expected some of these traits, but the overall impression that Stallman makes in person is hard to define. He is neither as obnoxious as detractors paint him, nor as selfless and charismatic as some supporters insist . Although, after meeting him, you can see how all these depictions originate, like any person, Stallman is more than the sum of such caricatures.

Stallman on stage

The fragmentary impressions I got of Stallman off-stage were reinforced when he got up to speak. Like many professional speakers, he immediately gains animation and energy when handed a mike, no matter how tired he is beforehand.

Stallman spoke for well over two hours, not using notes, but obviously covering ground (In this case, his view of copyright law) that he had gone over many times. He was fluent, with few if any pauses or interjections, but not particularly eloquent. Think of a university instructor who keeps his classes interested without being arresting or given to flights of rhetoric, and you have the right impression. The two hours went by quickly, and the audience showed no signs of boredom.

As an argument, Stallman’s speech was concrete, full of examples ranging from the personal to the legal, often enriched with small jokes, and structured with extreme clarity.

If I had to summarize Stallman’s speech in a single word, that word would be “focused.” When Stallman lays out an order to his points, he always returns that order, no matter how many digressions intervene – and, generally, he allows himself very few.

One thing that comes through very clearly as he spoke is his absolute sincerity and conviction. Whatever else anybody might think of him, those are never in doubt. He is quite willing, for instance, to do without a cell phone, DVDs with DRM, or anything else that he cannot use with a clear conscience.

But, as I watched his argument develop, what struck me was not so much any brilliance (although clearly Stallman has an above average intelligence), but his thoroughness. Although other people might possibly make connections or reach conclusions faster than he could, few could think topics through as carefully as Stallman.

In particular, Stallman pays close attention to how issues are framed by language. For example, he rejects the term “piracy” for file-sharing, pointing out that its main purpose is to demonize the practice, not to suggest an accurate analogy. Conversely, he talks about “the war on sharing,” doing his own bit of framing.

This is the same concern, of course, that leads him to insist on referring to GNU/Linux. Many people reject this idea without thinking, but, once you realize that, for Stallman, defining the terms is a necessity for clear thinking, then you realize that he is not simply being pedantic. He is well aware that language is rarely, if ever neutral, and, quite unsurprisingly, tries to influence the debate so that it is on his terms, or at least neutral.

If Stallman’s speech had a weakness, it is that he did not always think on his feet. Several times during the questions at the end, he seemed mildly at a loss, and could only refer back to his speech or declare – sometimes arbitrarily – that a questioner’s topic was irrelevant. Once, when a questioner went on and on without getting to the point, all he could do was seize on a careless use of “open source” rather than “free software,” instead of moving to take direct control of the situation. But perhaps fatigue had a lot to do with this behavior.

Watching the crowd

At any public event, watching the audience can be as rewarding as listening to the performance, and Stallman’s speech was no exception. Some audience members, I later learned, also attended his speech earlier in the day, as well as the one on the next day. However, even without that knowledge, I would still unhesitatingly describe the crowd as geeks with a small smattering of spouses. Most clearly had some familiarity with free software and Stallman’s ideas, and had not come to be challenged so much as to glimpse someone famous.

A minority had a slightly more ambitious goal: To engage Stallman, however briefly, in conversation. Since Stallman’s reputation and manner discouraged most from approaching him informally, some found a moment by getting him to autograph copies of his book, others by asking questions at the end. Many of those lining up up the mikes to each side of Stallman did not have an actual question, so much as a statement they wanted to make to Stallman. One or two seemed inclined to argue with him.


So what do these impressions add up to? A public event is not the place to get to know anybody, and Stallman would probably be a difficult man to get to know under any circumstances. What I saw was the public figure, with – perhaps – the occasional flash of the private man, both accustomed to his fame and occasionally irritated and trapped by it.

In the end, it occurs to me that a distinction between the public and private Stallman many not be worth making. He reminds me of the portrayal of the Wart (King Arthur) in T. H. White’s The Once and Future King. White depicts Arthur as someone inspired by a great idea that took over the rest of his life. In something of the same way, Stallman appears to have been struck by the idea of free software in the early 1980s. The decades since then, I suspect, have simply been filling in the details and taking the idea to its logical conclusions – until now it is hard for a casual observer like me to say where the public man ends and the private one begins.

Read Full Post »

Six weeks ago, I wrote that freelancers were better equipped than full-timers to survive a recession, because they were more accustomed to looking for work. At the time, I had only the vaguest suspicions that I would be putting my confident words to the test less than ten days later. Linux.com, which was buying most of my articles, was going along much the same as usual, and, and, because SourceForge, its parent company, is publicly traded, I knew it had money in the bank. If anyone were recession-proof, then surely I was. And, in the end, I was right, although not in the way that I had expected.

By freelancing standards, I had grown complacent. Ordinarily, I try to diversify my sources of income. But I was already writing the maximum number of stories that I could write per month without increasing my work hours, so I hadn’t done so as much as I might. Instead, I had allowed myself to become heavily dependent on a single buyer.

Imagine my surprise, then, when my main buyer suddenly stopped buying stories – just in time for Christmas.

After I picked myself up out of the bomb crater, my first reaction was relief that I had at least diversified enough that I could cover my monthly expenses. But I wouldn’t have much left over, and I didn’t feel like giving up my newly acquired art habit, even if it is a luxury.

As I exchanged a flurry of emails and IRC conversations with my fellow writers, I realized that I had to move at once. Quickly putting together a mental list of the most likely buyers for articles on free and open source software, I sent out some queries – not detailing what was happening, but simply saying that some slots in my writing schedule had opened up.

The results, to say the least, were gratifying. Five hours later, I had replaced 85% of the income I had obtained each month from my main buyer. Within three days, I had not only replaced it all, but had done so with a reduced work load. I didn’t even have to go through half my list of potential buyers, although I still might.

Of course, for the past month, I’ve been kept busy getting to know new editors and their ways of doing things. Also, there was paper work — all the more so because I’m a Canadian writing for American-based sites. But all that’s a small price to pay for self-preservation.

Am I lucky? I am painfully aware that I am, especially when I had let myself become so comfortable. But, to some extent, I made my own luck. I still had enough of a freelancer’s instinct to know what I had to do, and that I had to do it fast before anyone else did. And, apparently, despite the vocal minority that like to badmouth me, I seem to have developed a reasonably good reputation – in fact, some of that reputation seems founded on the grounds that anyone badmouthed by certain people must be all right.

Still, my escape was far too close for me to be self-congratulatory. To some extent, I’m still in panic mode.

I don’t know if Linux.com will still be a market for me when the dust clears. But, just now, I doubt that I will return to becoming so dependent on it – or any other single outlet. More than anything else, I am coming out of the last month with my belief intact: As a freelancer, I really was equipped to handle recession.

Read Full Post »

For eight years, I made most of my income from technical writing. Not the relatively glamorous technical writing involved with writing articles about free and open source software (FOSS) – glamorous, that is, to those who haven’t done it (those of us who have done it are usually considerably less starry-eyed) — but basic how-tos and detailed instructions to accompany hardware and software. Looking back, I must have been reasonably good at the job, since I went from a beginner to a consultant with a sub-contractor in eight months, and kept myself steadily employed most of the time and well-employed much of the time.

Based on that experience, I would like to offer some advice for those who are trying to fill the gaps in FOSS documentation. It’s a thankless job, under-appreciated and laborious, but, if you’re going to attempt it despite all the disincentives, you might as well do it properly. After all, your satisfaction in doing the job properly might easily be your only reward:

  • You must become an expert in what you are writing about: Some professional technical writers pride themselves on being specialists in communication, and feel they don’t need to know the details of what they are writing about. You can always tell manuals done by them, because they are shallow and have large gaps in them. Likewise, you can always tell this type of technical writer, because they’re despised by any developer with whom they work. The truth is that, while you don’t need to be an expert when you start documenting, if you aren’t expert by the time you’re finished, you aren’t doing the job properly.
  • It all comes down to structure: Anybody with average intelligence or better can learn to write a coherent sentence or paragraph. However, structuring several hundred pages is hard work – much harder work than the actual writing. The need to structure is also why you need to become an expert in your subject; if you’re not, how can you know what information to put first, or what’s missing? Don’t be surprised if you spend 50-75% of your time in planning the structure, or if your first outline changes drastically as you work. Both are indications that your work is developing the way that it should.
  • In the majority of cases, the best structure will be a list of tasks, arranged from the most basic or earliest to the most complex or latest: It will almost never be a list of menu items and taskbar icons, except in brief introductions to the interface. This task-orientation is a major reason why you need to be an expert in what you are writing – if you’re not, you won’t have any idea of what users might want to accomplish.
  • Think of your audience as being attention-deficit: Knowing your material is necessary, but it can also make you forget what new users need to hear. The best way to write to the level you need is to project yourself imaginatively into the position of a new user, but, if you can’t manage that, imagine that you are writing for people with low attention spans who are easily bored. The result may spell out the obvious for some readers, but other readers will be glad that you are thorough. Always remember: What is obvious to you isn’t obvious to your readers.
  • Don’t worry about style: In fiction, writers often call attention to their style. By contrast, non-fiction like technical writing is not about you. Your job is to provide simple, clear prose in which you are invisible. And if that sounds boring or unchallenging, you might consider Isaac Asimov’s observation that stain glass windows have been made for over a millennium, while clear glass was a much later development. In many ways, writing simply and clearly is much harder than writing with flourishes and personality. Focus on clarity and content, and let other style considerations take care of themselves. You’ll be surprised how well they work out without you thinking consciously about them.
  • Use structured prose whenever possible:Bullet lists, numbered lists, tables, and callouts on diagrams – all these techniques are conciser and easier to understand than straight prose
  • Your first draft is probably going to be terrible: But that doesn’t matter, so long as it improves by the end. What matters in the first draft is getting something that you or others can analyze for gaps and make estimates about the finished documentation from. Probably, the physical act of writing will be no more than 25% of your time. Often, it will be much less. If you’re planned properly, and begin writing with a thorough understanding, it should almost feel like an afterthought.
  • Don’t mix writing and editing: Writing is a creative process, editing a critical one. If you try to mix the two, you will probably do both poorly. You may also find yourself freezing up and being unable to write because your self-criticism is interfering with your ability to write.
  • Make sure editing is part of your schedule: Editing should not be a last-minuted effort. Instead, accept it as an important part of your schedule. Expect it to fill 10-20% of your time.
  • Editing is about structure as well as words: Editing is not just about spelling or correcting grammar. It’s just as much about the structure of the work.
  • Get second and third opinions: When you have just finished writing, you are probably unable to judge your work effectively. Get other people to review your work in as much detail as possible. If you can’t get other people to review, put the manuscript aside for several days. If you can’t put it aside, print it out, or take a break before returning to it.
  • Expect revisions: Based on my experience teaching first year composition at university, I can say that the average person takes 3 to 4 drafts to produce their best work. You may be naturally talented or reduce that number with practice, but don’t count on either until you have some experience.Make sure you budget the time. You’ll know if your efforts are succeeding if the general trend is that each draft becomes quicker and quicker to write. If that doesn’t happen – especially if you have to keep reinventing the structure or making major additions – then something is probably seriously wrong.

With any given piece of writing, you may not be able to follow each of these pieces of advice. Deadlines in particular may keep you from giving each of these points the attention it needs. But keep all these points in mind, and you will be more likely to write documentation that people actually use, instead of an after-thought to the software that is never used.

Read Full Post »

As a journalist, I don’t often come straight out and endorse anything. Having worked as a marketer, I have had a strong reaction against hype of any sort, including my own. Nor is endorsement my style. Anyway, just by writing on an issue, I can often do far more by encouraging others to support it than I could if I were to volunteer time or money. However, every once in a while, a cause comes along that is so obvious worthy that I make an exception.

Take, for example, the Free Software Foundation’s high-priority list. How anyone who is the least interested in free and open source software (FOSS) could not support this cause is almost inexplicable to me.

As you may know, the Free Software Foundation (FSF) and thousands of other groups have been working for years to create a computer environment that users control – one that they can use on as many computers as they want, that doesn’t require registration or activation, and doesn’t report on your activities to the manufacturer without your permission. That environment is almost there, in the form of GNU/Linux and a few other operating systems like FreeBSD. Only a few gaps such as an unecumbered Flash player and 3-D drivers for the leading video cards remain to be done, and they should be ready in a matter of a few years.

The high priority list is a way to call attention to these last remaining gaps in functionality. A couple of weeks ago, the FSF relaunched it as a campaign, soliciting donations to help in the development of the needed applications. These donations will not be used to pay developers directly, but may be used for such purposes as organizing face to face developer sprints to help the projects developing the applications, or to make people aware of the need.

The donations were kicked off by Russell Ossendryver of Worldlabel.com, whom I like to think of as a friend I haven’t met yet. Russell is a small business owner, but believes in free and open source software enough that he has pledged $10,000 to the high priority list.

You can argue over which applications are needed most, and about the content of the list (and the FSF encourages you to submit your thoughts). Very likely, you can’t match Russell’s donation (I can’t myself).

But if you have any interest whatsoever in FOSS, the high-priority list is a matter of getting down to basics. What could be more basic than finishing the free desktop? That’s been the goal all along – not our present 90% free and 10% doing without or compromising with proprietary software for the sake of expediency, but a completely user-controlled desktop. Anyone involved with FOSS who doesn’t donate what they can, or at least join the discussion about what should be on the list should ask some serious questions to themselves about their own sincerity.

With support, the FSF’s relaunching of the high priority list could be one of the major moments in FOSS. What more can I say, except to repeat my request to support it?

And before you ask, yes, I plan to sync my money with my mouth and send my own small cheque before the end of the year. Like I said, this is one time that my usual words in public aren’t enough.

Read Full Post »

Much to my bemusement, I see that James Maguire has listed this blog as one of the top 200 technology blogs, in the GNU/Linux/ Free and Open Source category.

James is my editor at Datamation, who shows amazing toleration for my inability to edit my own work, so I already know him for a decent sort. So, I figure he just needed to round out the spaces he had allotted for the category. Not that I don’t appreciate the honor, but I can see myself clearly enough to know that I don’t deserve it.

For one thing, look at the company I’m keeping. My entries here certainly aren’t a match for the varied articles at Linux.com, which is also on the list. Nor do they come close to the combination of astute legal analysis and wonky opinion on Groklaw. As for equating my efforts here with the industry analysis in the blogs of Mark Shuttleworth, Jim Zemlin, or Matt Assay – no way, man, as we used to say in my increasingly distant youth. I mean, I didn’t call this blog “Off the Wall” at random, you know what I mean?

What is really ironic is that, when I started this blog, I intended it as a place where I could write about things other than free and open source software. At the very most, it would be a sandbox for ideas that weren’t ready to be articles, or ones that I didn’t think I could sell. Nor do I often write on such topics, although I have plenty to say about my life as a journalist who covers such topics.

Yet, if I’m being honest, I have to admit that, when I do cover free and open source topics directly, the posts attract an entire order of magnitude more readers than my other topics. And I mean that literally, without any exaggeration whatsoever. So, maybe James is right, and this is a technology blog after all.

Anyway, I was taught that, if someone pays you a compliment, you say thanks and smile warmly – especially if the compliment isn’t true. So, that’s exactly what I’m going to do, figuratively speaking.

Read Full Post »

« Newer Posts - Older Posts »