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 DisqusIssue 220/2019
Buy this issue as a PDF
News
-
Linux Kernel Continues To Offer Mitigation for Spectre Mitigation
Kernel 4.19 has added another family of Spectre vulnerabilities to its list of mitigating the mitigation.
-
SpeakUp Trojan Targets Linux Servers
It’s exploiting a known vulnerability.
-
KDE Plasma 5.15 Beta Arrives
Major improvements to software management.
-
Canonical Announces Latest Ubuntu Core for IoT
Now offers 10 years of support.
-
GitHub Offers Free Private Repositories
Popular source code collaboration site makes a major change to feature set.
-
Linus Torvalds Welcomes 2019 with Linux 5.x
Better support for GPUs and CPUs.
-
Keep your edge with these powerful Linux administration tools:
Watching the Bad Guys with Cowrie
Trigger Admin Tasks with Systemd
Become a certified Linux Admin professional with the Linux Professional Institute LPIC-1 Systems Administrator certification.
-
Microsoft Gets an Open Source Web Browser
The company will use Google Chromium web browser as the foundation for its next browser.
-
Canonical Launches MicroK8s
Deploy Kubernetes in a few seconds.
-
A New Raspberry Pi Board
The new board packs everything that you get in Raspberry Pi 3B+ in a smaller package.