Shedding commercial attitudes towards documentation
Off the Beat: Bruce Byfield's Blog
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 reputation: Most technical writers know nothing about technology, and the documentation they produce is worthless. The average technical writer is an English major, and is as apt to be attached to the marketing department of a company as to development or quality assurance. In other words, they have little feel for technology, and are encouraged to think of what they produce as a cosmetic extra rather than a necessity.
Of course, technical writers could overcome these handicaps if they wanted. I have an English degree myself, yet I had few problems finding work because I realized early that I needed an expert understanding of what I wrote about.
But this is a minority opinion. The majority of technical writers are under the illusion that all they need are language skills. They see no need to know technology and code. If anything, they look down on this knowledge as less important than grammar and spelling.
With this attitude, the documentation that most technical writers produce may be clear and concise, but it is also superficial and incomplete, and displays no more than a rudimentary knowledge of the software or hardware they are writing about.
So, naturally, developers despise writers and what they produce. In the eight years that I was a technical writer, I got used to having to prove my competence at the start of each new contract. Experience had taught me that other writers had muddied the waters before me.
Just in time documentation
At the same time, commercial developers and project leaders have very little sense of how useful documentation is produced. For a long time, pundits on the subject of technical writing have insisted that writers have to be involved in the development process as early as possible. Yet, in my experience, not one company in six has adopted this practice.
Instead, documentation begins near the end of the development process. Often, it begins ridiculously late -- I have worked on projects in which I was expected to document software with a dozen modules in less than a week, and the best I could do was triage.
Yet, even when the time allotted for documentation is more reasonable, bringing writers in near the end of the project rarely works. Already pushing deadline, the writers are under still more pressure because they have to learn about what they are documenting. Even if they only learn the bare minimum that most writers settle for, their productivity is impaired. To do a proper job and actually understand their subject is next to impossible.
Moreover, at the same time that writers are gearing up, developers -- their main source of information -- are winding down. Often, the developers feel that educating the writers is not their job, or they are ready to relax and disinclined to have writers pick their brains. At times, they go on vacation, leaving writers to struggle on alone.
These same attitudes apply when developers do their own documentation in the form of comments or FAQs. Just like a student writing an essay, who pounds out the bibliography as an afterthought, the average commercial developer writes documentation only after their main work is done, expending minimal thought and less effort, and not thinking how it might be useful to others.
In other words, the prevailing attitude in commercial development is that documentation is of secondary importance. Developers might be fond of advising people to RTFM (Read the Fucking Manual), but everybody still jokes that nobody really reads documentation. The marketing department might want it, but everyone knows that those drones are obsessed with the superficial, right?
Searching for a free software alternative
The division between commercial and free software is not firm. Most free software developers have also worked on commercial software. In fact, these days, free and commercial software can even be the same work. One of the results of this inter-connection is that much of the free software community views documentation as an extra and not a part of their job.
True, many projects, including Drupal, Fedora, and KDE, have struggled to change this attitude. But at times the old commercial attitudes still seem to faintly linger. How often, for example, do you see writers blogging alongside developers on Planet feeds for major projects? At least to some extent, writers and other non-developers still seem to have less status than coders, and to receive less credit as well. Unofficially, writers often seem less part of the community than developers.
This inheritance from the commercial world is not only counter-productive, but needless. Free software technical writers may not be coders any more than their commercial counterparts are, but, given that they are involved in free software, they are unlikely to think they don't need to understand the project they are working on. And, unlike in the commercial world, where technical writing is the last refuge of English majors who can't find a teaching gig, free software technical writers presumably like what they are writing about.
Similarly, despite the move towards twice-yearly releases in many large projects, there is no reason for documentation to be a rushed effort at the last minute. So long as writers can compile source code, they can learn about the software while it is being revised. Nor, in most cases, is there any reason why a release couldn't be delayed until the documentation is ready.
In the same way that the free software has produced superior applications, its projects are positioned to produce superior documentation as well. But, to do so, projects have to shed attitudes that do not apply to their situation. The only question is how many are willing to do so.
Comments
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
-
AlmaLinux 10.0 Beta Released
The AlmaLinux OS Foundation has announced the availability of AlmaLinux 10.0 Beta ("Purple Lion") for all supported devices with significant changes.
-
Gnome 47.2 Now Available
Gnome 47.2 is now available for general use but don't expect much in the way of newness, as this is all about improvements and bug fixes.
-
Latest Cinnamon Desktop Releases with a Bold New Look
Just in time for the holidays, the developer of the Cinnamon desktop has shipped a new release to help spice up your eggnog with new features and a new look.
-
Armbian 24.11 Released with Expanded Hardware Support
If you've been waiting for Armbian to support OrangePi 5 Max and Radxa ROCK 5B+, the wait is over.
-
SUSE Renames Several Products for Better Name Recognition
SUSE has been a very powerful player in the European market, but it knows it must branch out to gain serious traction. Will a name change do the trick?
-
ESET Discovers New Linux Malware
WolfsBane is an all-in-one malware that has hit the Linux operating system and includes a dropper, a launcher, and a backdoor.
-
New Linux Kernel Patch Allows Forcing a CPU Mitigation
Even when CPU mitigations can consume precious CPU cycles, it might not be a bad idea to allow users to enable them, even if your machine isn't vulnerable.
-
Red Hat Enterprise Linux 9.5 Released
Notify your friends, loved ones, and colleagues that the latest version of RHEL is available with plenty of enhancements.
-
Linux Sees Massive Performance Increase from a Single Line of Code
With one line of code, Intel was able to increase the performance of the Linux kernel by 4,000 percent.
-
Fedora KDE Approved as an Official Spin
If you prefer the Plasma desktop environment and the Fedora distribution, you're in luck because there's now an official spin that is listed on the same level as the Fedora Workstation edition.
online marketing
www.onlineuniversalwork.com
hai friend
Affiliate Marketing is a performance based sales technique used by companies to expand their reach into the internet at low costs. This commission based program allows affiliate marketers to place ads on their websites or other advertising efforts such as email distribution in exchange for payment of a small commission when a sale results.
www.onlineuniversalwork.com
online marketting
www.onlineuniversalwork.com
floss manuals
We have been going now for about 2 years and we have many many excellent docs about free software mostly in English (http://en.flossmanuals.net) but also we have an Finnish community (http://fi.flossmanuals.net) and a Farsi community (http://fa.flossmanuals.net) and also many manuals being translated into various languages (see http://translate.flossmanuals.net/write).
for the linux community there is much of interest, but probably most interesting is the excellent introduction to the command line manual which we produced in collaboration with the FSF:
http://en.flossmanuals.net/gnulinux
You can buy it here:
http://shop.fsf.org/
We produce community authored content and we often do this in 2-5 days. For example the following were produced in 5 days :
http://en.flossmanuals.net/civicrm
http://en.flossmanuals.net/CircumventionTools
http://en.flossmanuals.net/Inkscape
http://en.flossmanuals.net/opentranslationtools
http://en.flossmanuals.net/ardour/
http://en.flossmanuals.net/theoracookbook
http://en.flossmanuals.net/sugar
and the following were written in 2 days:
http://en.flossmanuals.net/gnulinux
http://en.flossmanuals.net/GSoCMentoringGuide
http://en.flossmanuals.net/firefox
We also produce books. All of the above are available in printed form (see bookstore on the right of the front page).
We also have produced books in other languages including the recent 'How to Bypass Internet Censorship' book ( http://objavi.flossmanuals....nslate-2009.12.01-12.02.55.pdf ) which was printed in Arabic for the recent Arabic Bloggers conference (http://advocacy.globalvoice...05/2nd-arab-bloggers-meeting/) held in Beirut.
General Issue - Many Find it Hard to See Things From Others Perspective
The General problem, and there's been a lot of slagging of "coders" as illiterate unable to write English gone on in these Documentation threads, is the difficulty people have of understanding and putting themselves in other's position. Perfect Docs. for one user, is poor for another; those complaining about UNIX man pages not making sense, to me simply show laziness and lack of effort they normally make perfect sense to those familiar with UNIX concepts.
MS Windows documentation & help, available on the machine, is to my mind an example of outstandingly poor work, it just repeats the obvious, normally what is on the screen; and one has to access Google & Knowledge Base for true enlightenment. Why repeat what the application is telling you anyway, and give no more information than what someone with a clue can easily extrapolate.
Different documentation level templates
A good friend tried to explain how a large network was connected using drawings connected to further documentation below. The picture showed the components, but failed completely at showing the true relationship between them. Using the standard network "lightning bolt" between the firewalls failed, because it did not show in which direction traffic was allowed between the components. The drawing explained very little to new network engineers in the company, but it had pretty colours and made the administration happy.
Talking about code or code comments as documentation is rubbish. The code is one of several possible ways of explaining to the computer what you want it to do for you. Documentation is what the computer needs from you to do it. We write documentation for our future selves or for other people. We write documentation to explain our intent, not what the code actually does - which might be faulty. If it does what we intended it to do, there is no need to look at the code at all. However, this is not true for the documentation, because our intent must be explained to new users over and over again until they know what to do.
I am willing to argue the true reason for the success of projects like MySQL and PHP is the documentation. This is true of companies like Cisco in the networking industry. All of these allow users to comment on every single aspect of the products. Use them as templates for how to do it right, borrow their structure - a short introduction about the intent, a short tutorial, and then more advanced stuff, and finally references if any.
I'm running Kubuntu 9.10 Netbook remix right now. Please, do this short exercise: find the documentation that explains how to add and remove your favourite applications from the Favourites container on the plasma workspace. I'll explain it first, so you have several clues you can use to find the documentation: click on the yellow star on the program icon to add the software, click on the red minus sign to remove it from the Favourites container.
The best of luck!
No difference between commercial and open source
primary documentation to developers
Secondary documentation is the comments in the source code, which is dismal. Most of the time, it is not there, or is a rehash of the program code in pseudo-english, and is often wrong, it does not accurately describe the real code.
Knuth tried, inventing literate programming, Sun tried, with javadoc sections in source code files. Most programmers are simply not literate and articulate enough to write lucid, accurate descriptions.
Someone should have taught them how to write English (or Chinese or Hindi or whatever human language they use) declarative sentences and paragraphs when they were about 12 years old. Now it is too late, the only grammatical tense they can speak or write is second person imperative: (computer) do this !
FOSS documentation
When I started my 4tH project I was dedicated to produce excellent documentation on each and every level, because it would boost the usefulness of the project. I got comments from my peers and produced a generalized Forth tutorial which still comes with several other commercial and FOSS products on the subject. It did even inspire others to make similar documentation. A good example makes people follow you in that respect, I think.
I know that people producing documentation are not in high regard, which is unjust, because making good documentation is an art, just like software. It would absolutely help the cause of FOSS if they would do better in that regard.
As far as I'm concerned, no release EVER came with an updated manual, but then again I can choose when I make a new release. When making software at work, it at least has user documentation - time can get tight - but the rest WILL follow. No product can simply do without.
The wrong approach to (technical) documentation