Feeds:
Posts
Comments

Archive for the ‘software development’ Category

Stepping away from evangelism

Posted in Bruce Byfield, FOSS, freesoftware, open source, Personal, software development, Uncategorized, tagged , , , , , , on April 11, 2009| 7 Comments »

I am a firm supporter of free and open source software (FOSS). These days, though, I rarely evangelize about FOSS when face to face. While I will argue in favor of FOSS in articles, or in speeches, I hardly ever do so in casual conversation.

Part of the reason for this reticence is politeness, a sense that inflicting my views unasked is bad manners, no matter what the subject or my interest in it. Another part is my anarchistic inclinations; while I have firm beliefs on the subject, I am mostly content to leave other people to their own beliefs, unless they are trying to denigrate mine or inflicting theirs unasked. However, mostly, my reticence is based on my growing conviction that evangelism is rarely effective.

This conviction struck me harder than every the other night, when we were at a gathering at our neighbors’. Another guest asked what I did for a living, and I explained that I was a journalist who wrote about free and open source software. After warning the other guest that I could talk for hours on the subject, I started to explain. I soon had three reactions that I have grown wearily familiar with from past efforts to talk about FOSS.

One female guest frankly refused to believe anything I said. Microsoft did not own her software, she insisted, nor could it record information about her activities or the legality of her software. GNU/Linux couldn’t be free of cost, either. Nor could it be possibly be less prone to malware and viruses than Windows. She was willing to consider the possibilitiy that the Egyptian pyramids were built by aliens, but not a few facts that anyone with an Internet connection can quickly establish.

The second reaction was from the male host. He regularly downloads movies from – let us say – sometimes questionable sources, and has suffered from malware and viruses in the past. At least once, he had to have his computer purged by an expert.

Yet this man thought that the security built-in to GNU/Linux was too much trouble. In fact, he thought that having separate administrative and user accounts was too much trouble. I had helped him set them up on his latest Windows machine, but he had soon changed them so that every account had administrative privileges. I asked him what was so difficult about taking ten seconds to switch accounts, and all he replied was, “I know you think it’s a foolish decision, but for me the security just isn’t worth the effort.”

I started to ask him if he though having an infected machine and having to spend money on software and assistance wasn’t more of an effort, but then the guest who had started the conversation thread announced that the discussion was boring. From the look on several other faces, I realized that, for them it was.

“I guess that’s a hint,” I said with a smile. But, inwardly, I was thinking: These are people who social activists. They are concerned and can speak with some knowledge about the hardships faced by the average Palestinian in the Middle East, the state of education, anti-poverty measures, and environmentalism. Yet none of them could see that I was talking about issues close to their senses of self-identity and about concrete steps they could take to put their ideals in practice in their computing – not even when I spelled out the connection in so many words. They spend hours on the computer most days, yet they did not care about realizing their ideals in their daily life.

Faced with such massive indifference and disbelief, I could either go into full rant mode or keep silent so as not to spoil the evening. I was tired, so I chose not to spoil the evening.

The encounter was not surprising, nor particularly unpleasant. All the same, it and countless similar encounters have made me keep my evangelism quiet. These days, I state my position only when asked, and stop expressing it when other people look bored.

It’s not that I care so much whether people think I’m obsessional. Rather, I hate being branded as such for no useful purpose.

Read Full Post »

12 Tips for Writing Free Software Documentation

Posted in British Columbia, Bruce Byfield, Business, documentation, Free Software, freesoftware, journalism, open source, Personal, software development, technical writing, Uncategorized, writing, tagged , , , , , , , on December 15, 2008| 1 Comment »

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 »