Off the Beat: Bruce Byfield's Blog

Last week, I wrote about the problems of writing documentation for free software. This week, I'd like to write about the practical challenges -- specifically, what knowledge you need to write free software documentation, and the available sources of information. To take advantage of the information available, you need a reasonable grasp of the written language. Contrary to the impression that many salaried technical writers give, you do not necessarily need to know how to parse a sentence or be a wizard at the black arts of grammar. Text that requires minimal editing is always an asset, but free software documentation is a communal effort. If you're lucky, another documenter can...

Six years ago, I made my living as a technical writer. I wouldn't want to return to the profession, but, when Esther Schindler recently blogged about the importance of detailed code comments and Carla Schroder about the need for better documentation in free software generally, I noticed. But, as much as I agree with Schindler and Schroder, I wonder how much of the community is about to give it the attention it deserves. Too much of the community still seems to cling to attitude about documentation inherited from commercial development.Attitudes to writers (and why they deserve them)Part of the problem is that technical writers are held in low regard. There is a simple reason for this...

One application I am always looking for is a better desktop wiki. Not for collaboration, but for dumping various pieces of information into as I research and organize them. For a time, I used Basket Note Pads, but I drifted away when it didn't run on KDE 4.x and the original maintainer quit. Happily, the project has overcome both those setbacks and is moving slowly towards a new major release.Basket is one of those applications that you can navigate at a glance. The left pane serves as a table of contents, showing a hierarchical structure of baskets -- containers for various bits of information. On the right is a detailed view of the basket currently highlighted in the left pane. To add a...

For years, Linux in a Nutshell's third edition has been the closest book to my keyboard. The new sixth edition -- the first in several years -- is going to continue that tradition. The new edition shows the same indispensable qualities as its predecessors, giving an accurate snapshot of the operating system, solid introductory information, and concise, accurate command summaries in a well-organized format.Changes in TechnologyOne of the reasons I value Linux in a Nutshell is that its editions provide an accurate summary of the current state of GNU/Linux technology. You can tell from the topics alone how the technology has changed from edition to edition. For instance, in the sixth...

Like many people, I've always had a few tracks of music on my computer. However, I've only started taking a strong interest in music players since I started digitalizing my music collection a few months ago. I'm relatively sure that Amarok will handle the 50 or so gigabytes of music that I'll have when I'm done, but for the netbook I'm thinking of buying, I've been looking for something lighter. Currently, I'm thinking that Goggle Music Manager (GMM) may be the lightweight and easy to use player that I need (that's "Goggle," please note, not "Google" -- although, just to add to the confusion, Goggle is hosted on Google).GMM packages are available for several...

Joe Brockmeier, my one-time colleague at Linux.com, has been blogging recently about how to present free software to non-technical users. He suggests that the community approach the problem as a marketing exercise, emphasizing benefits rather than the ethical issue of freedom. My own take is somewhat different: The problem is not so much talking about ethics as the fact that we have not been talking about the benefits of ethics. Instead of the four freedoms that appeal to developers, we need a similar list that explains what advantages free software offers for ordinary users.Much of my thinking on this issue stems from an interview I did in 2006 with Peter Brown, the executive director of...

Whenever ideas run short, columnists and bloggers like to pontificate about why free and open source software isn't more successful. Inevitably, they trot out the same old explanations. Microsoft's monopoly, lack of vendor support, community unfriendliness and infighting, and inertia are some of the most popular ones. Not having anything new to contribute (or any shortage of ideas to run about), I've avoided such discussions until now. Recently, though, my efforts to persuade people to use free software have suggested to me an explanation so simple that it is seldom mentioned -- people just don't understand the concept, or why it should interest them. The whole idea runs so counter to the...