Linux Journal Offers Artistic Immortality

What's that Linux Journal article doing in /usr/src/linux/Documentation?

In order to make it easier for users to evaluate and learn to use free software available on the Internet, Linux Journal will be changing our author contract to encourage authors to contribute articles to free software or free documentation projects after they have been published in Linux Journal.

Contributors already are taking advantage of the policy, which promises to help people browsing the Web for new free software to try. It will also keep documentation up to date. The option of contributing articles to free projects has been available to Linux Journal authors since its founding. It is now being added to the author contract to make it clear to all authors that the option is open to them.

Linux USB maintainer Greg Kroah-Hartman, who wrote a Linux Journal article on USB device drivers that was recently accepted into the Linux kernel source tree, said he is happy with the new policy. "It will allow projects to offer professional grade documentation directly with their software, making it easier for users to have access to it", he said. Kroah-Hartman recently began writing a new column on device drivers for Linux Journal, and he said plans to submit the columns as well. The USB article originally appeared in the October 2001 issue, and it is in the kernel as of version 2.5.3-pre6.

Keeping articles in software distribution channels will help keep them up to date, as people who modify the code can check and fix the relevant documentation at the same time. "If the software changes, the documentation must be updated to reflect these changes", Kroah-Hartman added. "This ensures that anyone who picks up the software package for the first time reads the correct information. If any user realizes that what they have read is different from what the software really does, they will instantly start to doubt all of the documentation."

Nick Moffitt, who wrote the GAR software build system and the article "GAR: Automating Entire OS Builds", said that it is important to modify the bundled version of the article to match new functionality in the software. He writes:

Some major features of GAR have changed since I wrote the article from the May/June issue of Embedded Linux Journal. The GAR system now separates the notion of the compilation install directory (such as /home/rms/new_file_tree/) and the prefix (such as /usr or /). Because our software needs to know it has to look in /etc for config files when it runs, rather than /home/nick/build/etc/, this was extremely important.

But this also means that users and developers need to keep track of a new variable: $(DESTDIR). This single change has made a little more work for package maintainers, but it has improved the system's usefulness significantly. If the documentation were fixed in the pre-DESTDIR days, it could be devastatingly confusing and misleading to the user.

The only options in such a world would be to rewrite the documentation from scratch (a difficult task, especially if one needed to make the new documentation seem as different as possible from the original), ignore the documentation altogether (misleading the user) or abandon the project.

So much documentation is out of date these days, why bother deliberately creating this sorry state of affairs?

And, in answer to the question, "How will this help Artists?", Moffitt says:

"One of the reasons to produce Art is to ensure a sort of immortality. By allowing one's work to be kept relevant, this can be achieved. Richard Stallman hasn't written much code in gcc or gdb in a while, yet his contributions toward them would have been forgotten if he had not let others take the reins and keep them up to date. Per Cederqvist hasn't written much of the CVS documentation in years, yet it's still called "The Cederqvist Document".

"The ability to modify works provides a rich palette from which to construct new Art."

Don Marti is editor in chief of Linux Journal.

______________________

White Paper
Linux Management with Red Hat Satellite: Measuring Business Impact and ROI

Linux has become a key foundation for supporting today's rapidly growing IT environments. Linux is being used to deploy business applications and databases, trading on its reputation as a low-cost operating environment. For many IT organizations, Linux is a mainstay for deploying Web servers and has evolved from handling basic file, print, and utility workloads to running mission-critical applications and databases, physically, virtually, and in the cloud. As Linux grows in importance in terms of value to the business, managing Linux environments to high standards of service quality — availability, security, and performance — becomes an essential requirement for business success.

Learn More

Sponsored by Red Hat

White Paper
Private PaaS for the Agile Enterprise

If you already use virtualized infrastructure, you are well on your way to leveraging the power of the cloud. Virtualization offers the promise of limitless resources, but how do you manage that scalability when your DevOps team doesn’t scale? In today’s hypercompetitive markets, fast results can make a difference between leading the pack vs. obsolescence. Organizations need more benefits from cloud computing than just raw resources. They need agility, flexibility, convenience, ROI, and control.

Stackato private Platform-as-a-Service technology from ActiveState extends your private cloud infrastructure by creating a private PaaS to provide on-demand availability, flexibility, control, and ultimately, faster time-to-market for your enterprise.

Learn More

Sponsored by ActiveState