Tips for writing documentation
ROSE Blog: Rikki's Open Source Exchange
Yesterday I received a phone call from a grad school buddy who is now writing press releases and marketing for a technology company. I told my friend that her press releases were probably much better quality than the ones she received as an editor for a regional newspaper. She replied, "They're great until the engineers review them and change everything back into engineer-speak."
It's timely that this morning I ran across Carla Schroder's recent documentation blog posts: Tips for Documentation Writers (This Means You Too, Ace Coders) and More Tips for Documentation Writers (You Too, Ace Coders).
Of course, if you were in Janice Gelb's LISA presentation, "WTFM: Documentation and the System Administrator," your documentation has probably improved by leaps and bounds in the past few weeks. Janice's presentation slides and additional materials are still available online, too: http://www.usenix.org/events/lisa08/tech/tech.html#gelb
I'm also reminded of something an attendee said at Janice's session. He recommended that everyone read The Elements of Style . If you haven't read it in a while, it's not too late to add it to your Christmas wish list.
comments powered by DisqusSubscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.
News
-
System76 Announces the New Thelio Prime Desktop
The makers of the Thelio desktop line and Pop!_OS have released a powerful small form factor PC.
-
A Must See KDE Documentary
It doesn't matter what desktop environment you prefer, this KDE documentary should top your list of things to watch.
-
New KORA Linux Distro to Harness the Power of Local AI
The development team behind CyanogenMod, Android, and Playtron unveils KORA, a Linux distribution built specifically for AI nerds.
-
Epic Games Targets Linux for New Launcher
The Epic Games new launcher is still in preview, but it looks to land on several Linux distributions.
-
Fedora 45 Now Available
The latest iteration of Fedora has arrived with Gnome 51 and KDE Plasma 6.8.
-
Linux 7.4 is "Much Healthier" Thanks to AI
At nearly 42 million lines, Linux 7.4 is the largest merge in the kernel’s history.
-
Working Exploit for a Linux Kernel Flaw Made Public
Even before a bug received its CVE identifier or an upstream fix, the local privilege escalation vulnerability exploit found its way into the wild.
-
r/opensource Bans AI-Assisted and AI-Related Projects
The de facto subreddit for all things open source has not only banned AI-related projects but also users who "don't speak English."
-
Bottlenecks Discovered by Meta Engineers Lead to Scalability Improvements
Thanks to a small group of engineers at Meta, the Linux kernel module kernfs has been improved, which has led to some serious gains.
-
PwnEscape Poses VM Vulnerability
A guest-to-host escape flaw in Linux KVM, named PwnEscape, might be yet another means of attacking Linux.
