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.

______________________

Webinar
One Click, Universal Protection: Implementing Centralized Security Policies on Linux Systems

As Linux continues to play an ever increasing role in corporate data centers and institutions, ensuring the integrity and protection of these systems must be a priority. With 60% of the world's websites and an increasing share of organization's mission-critical workloads running on Linux, failing to stop malware and other advanced threats on Linux can increasingly impact an organization's reputation and bottom line.

Learn More

Sponsored by Bit9

Webinar
Linux Backup and Recovery Webinar

Most companies incorporate backup procedures for critical data, which can be restored quickly if a loss occurs. However, fewer companies are prepared for catastrophic system failures, in which they lose all data, the entire operating system, applications, settings, patches and more, reducing their system(s) to “bare metal.” After all, before data can be restored to a system, there must be a system to restore it to.

In this one hour webinar, learn how to enhance your existing backup strategies for better disaster recovery preparedness using Storix System Backup Administrator (SBAdmin), a highly flexible bare-metal recovery solution for UNIX and Linux systems.

Learn More

Sponsored by Storix