documentation : Dictionary / Wörterbuch (BEOLINGUS, TU Chemnitz)

Proverbs, aphorisms, quotations (English)	by Linux fortune

A bug in the code is worth two in the documentation.
A novice asked the Master: "Here is a programmer that never designs, documents, or tests his programs. Yet all who know him consider him one of the best programmers in the world. Why is this?" The Master replies: "That programmer has mastered the Tao. He has gone beyond the need for design; he does not become angry when the system crashes, but accepts the universe without concern. He has gone beyond the need for documentation; he no longer cares if anyone else sees his code. He has gone beyond the need for testing; each of his programs are perfect within themselves, serene and elegant, their purpose self-evident. Truly, he has entered the mystery of the Tao." -- Geoffrey James, "The Tao of Programming"
As long as there are ill-defined goals, bizarre bugs, and unrealistic schedules, there will be Real Programmers willing to jump in and Solve The Problem, saving the documentation for later.
Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing. -- Dick Brandon
Documentation is the castor oil of programming. Managers know it must be good because the programmers hate it so much.
Fellow programmer, greetings! You are reading a letter which will bring you luck and good fortune. Just mail (or UUCP) ten copies of this letter to ten of your friends. Before you make the copies, send a chip or other bit of hardware, and 100 lines of 'C' code to the first person on the list given at the bottom of this letter. Then delete their name and add yours to the bottom of the list. Don't break the chain! Make the copy within 48 hours. Gerald R. of San Diego failed to send out his ten copies and woke the next morning to find his job description changed to "COBOL programmer." Fred A. of New York sent out his ten copies and within a month had enough hardware and software to build a Cray dedicated to playing Zork. Martha H. of Chicago laughed at this letter and broke the chain. Shortly thereafter, a fire broke out in her terminal and she now spends her days writing documentation for IBM PC's. Don't break the chain! Send out your ten copies today! For example, if \thinmskip = 3mu, this makes \thickmskip = 6mu. But if you also want to use \skip12 for horizontal glue, whether in math mode or not, the amount of skipping will be in points (e.g., 6pt). The rule is that glue in math mode varies with the size only when it is an \mskip; when moving between an mskip and ordinary skip, the conversion factor 1mu=1pt is always used. The meaning of '\mskip\skip12' and '\baselineskip=\the\thickmskip' should be clear. -- Donald Knuth, TeX 82 -- Comparison with TeX80
`Lasu' Releases SAG 0.3 -- Freeware Book Takes Paves For New World Order by staff writers Helsinki, Finland, August 6, 1995 -- In a surprise movement, Lars ``Lasu'' Wirzenius today released the 0.3 edition of the ``Linux System Administrators' Guide''. Already an industry non-classic, the new version sports such overwhelming features as an overview of a Linux system, a completely new climbing session in a tree, and a list of acknowledgements in the introduction. The SAG, as the book is affectionately called, is one of the corner stones of the Linux Documentation Project. ``We at the LDP feel that we wouldn't be able to produce anything at all, that all our work would be futile, if it weren't for the SAG,'' says Matt Welsh, director of LDP, Inc. The new version is still distributed freely, now even with a copyright that allows modification. ``More dough,'' explains the author. Despite insistent rumors about blatant commercialization, the SAG will probably remain free. ``Even more dough,'' promises the author. The author refuses to comment on Windows NT and Windows 96 versions, claiming not to understand what the question is about. Industry gossip, however, tells that Bill Gates, co-founder and CEO of Microsoft, producer of the Windows series of video games, has visited Helsinki several times this year. Despite of this, Linus Torvalds, author of the word processor Linux with which the SAG was written, is not worried. ``We'll have world domination real soon now, anyway,'' he explains, ``for 1.4 at the lastest.'' ... -- Lars Wirzenius <wirzeniu@cs.helsinki.fi> [comp.os.linux.announce]
One of the questions that comes up all the time is: How enthusiastic is our support for UNIX? Unix was written on our machines and for our machines many years ago. Today, much of UNIX being done is done on our machines. Ten percent of our VAXs are going for UNIX use. UNIX is a simple language, easy to understand, easy to get started with. It's great for students, great for somewhat casual users, and it's great for interchanging programs between different machines. And so, because of its popularity in these markets, we support it. We have good UNIX on VAX and good UNIX on PDP-11s. It is our belief, however, that serious professional users will run out of things they can do with UNIX. They'll want a real system and will end up doing VMS when they get to be serious about programming. With UNIX, if you're looking for something, you can easily and quickly check that small manual and find out that it's not there. With VMS, no matter what you look for -- it's literally a five-foot shelf of documentation -- if you look long enough it's there. That's the difference -- the beauty of UNIX is it's simple; and the beauty of VMS is that it's all there. -- Ken Olsen, president of DEC, DECWORLD Vol. 8 No. 5, 1984 [It's been argued that the beauty of UNIX is the same as the beauty of Ken Olsen's brain. Ed.]
Our documentation manager was showing her 2 year old son around the office. He was introduced to me, at which time he pointed out that we were both holding bags of popcorn. We were both holding bottles of juice. But only __he had a lollipop. He asked his mother, "Why doesn't HE have a lollipop?" Her reply: "He can have a lollipop any time he wants to. That's what it means to be a programmer."
Real programmers don't draw flowcharts. Flowcharts are, after all, the illiterate's form of documentation. Cavemen drew flowcharts; look how much good it did them.
The flow chart is a most thoroughly oversold piece of program documentation. -- Frederick Brooks, "The Mythical Man Month"
Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29 29 printf ("Welcome to GNU Hell!\n"); -- "GNU Libtool documentation"
...we must counterpose the overwhelming judgment provided by consistent observations and inferences by the thousands. The earth is billions of years old and its living creatures are linked by ties of evolutionary descent. Scientists stand accused of promoting dogma by so stating, but do we brand people illiberal when they proclaim that the earth is neither flat nor at the center of the universe? Science has taught us some things with confidence! Evolution on an ancient earth is as well established as our planet's shape and position. Our continuing struggle to understand how evolution happens (the "theory of evolution") does not cast our documentation of its occurrence -- the "fact of evolution" -- into doubt. - Stephen Jay Gould, "The Verdict on Creationism", The Skeptical Inquirer, Vol XII No. 2
"Pseudocode can be used to some extent to aid the maintenance process. However, pseudocode that is highly detailed - approaching the level of detail of the code itself - is not of much use as maintenance documentation. Such detailed documentation has to be maintained almost as much as the code, thus doubling the maintenance burden. Furthermore, since such voluminous pseudocode is too distracting to be kept in the listing itself, it must be kept in a separate folder. The result: Since pseudocode - unlike real code - doesn't have to be maintained, no one will maintain it. It will soon become out of date and everyone will ignore it. (Once, I did an informal survey of 42 shops that used pseudocode. Of those 42, 0 [zero!], found that it had any value as maintenance documentation." --Meilir Page-Jones, "The Practical Guide to Structured Design", Yourdon Press (c) 1988
"(The Chief Programmer) personally defines the functional and performance specifications, designs the program, codes it, tests it, and writes its documentation... He needs great talent, ten years experience and considerable systems and applications knowledge, whether in applied mathematics, business data handling, or whatever." -- Fred P. Brooks, _The Mythical Man Month_
Arnold's Laws of Documentation: (1) If it should exist, it doesn't. (2) If it does exist, it's out of date. (3) Only documentation for useless programs transcends the first two laws.
Documentation: Instructions translated from Swedish by Japanese for English speaking persons.
MAFIA, n: [Acronym for Mechanized Applications in Forced Insurance Accounting.] An extensive network with many on-line and offshore subsystems running under OS, DOS, and IOS. MAFIA documentation is rather scanty, and the MAFIA sales office exhibits that testy reluctance to bona fide inquiries which is the hallmark of so many DP operations. From the little that has seeped out, it would appear that MAFIA operates under a non-standard protocol, OMERTA, a tight-lipped variant of SNA, in which extended handshakes also perform complex security functions. The known timesharing aspects of MAFIA point to a more than usually autocratic operating system. Screen prompts carry an imperative, nonrefusable weighting (most menus offer simple YES/YES options, defaulting to YES) that precludes indifference or delay. Uniquely, all editing under MAFIA is performed centrally, using a powerful rubout feature capable of erasing files, filors, filees, and entire nodal aggravations. -- Stan Kelly-Bootle, "The Devil's DP Dictionary"
manual, n.: A unit of documentation. There are always three or more on a given item. One is on the shelf; someone has the others. The information you need is in the others. -- Ray Simard
... we must counterpose the overwhelming judgment provided by consistent observations and inferences by the thousands. The earth is billions of years old and its living creatures are linked by ties of evolutionary descent. Scientists stand accused of promoting dogma by so stating, but do we brand people illiberal when they proclaim that the earth is neither flat nor at the center of the universe? Science has taught us some things with confidence! Evolution on an ancient earth is as well established as our planet's shape and position. Our continuing struggle to understand how evolution happens (the "theory of evolution") does not cast our documentation of its occurrence -- the "fact of evolution" -- into doubt. -- Stephen Jay Gould, "The Verdict on Creationism", The Skeptical Inquirer, Vol. XII No. 2.
Throw away documentation and manuals, and users will be a hundred times happier. Throw away privileges and quotas, and users will do the Right Thing. Throw away proprietary and site licenses, and there won't be any pirating. If these three aren't enough, just stay at your home directory and let all processes take their course.
"I would suggest you to read through the following book and files: * Kernighan & Pike, "The Practice of Programming" * Documentation/CodingStyle * drivers/net/aironet4500_proc.c and consider, erm, discrepancies. On the second thought, reading K&R might also be useful. IOW, no offense, but your C is bad beyond belief." - Al Viro
"Linux kernel development is dominated by a hacker ethos, in which external documentation is held in contempt, and even code comments are viewed with suspicion." - Jerry Epplin
"Once you realize that documentation should be laughed at, peed upon, put on fire, and just ridiculed in general, THEN, and only then, have you reached the level where you can safely read it and try to use it to actually implement a driver." - Linus Torvalds
Aren't we lucky our documentation is so sparse noone can accuse us of being inconsistent? 8) - Rusty Russell on linux-kernel
(I tried to get some documentation out of Digital on this, but as far as I can tell even _they_ don't have it ;-) -- Linus Torvalds, in an article on a dnserver
> I get the following error messages at bootup, could anyone tell me > what they mean? > fcntl_setlk() called by process 51 (lpd) with broken flock() emulation They mean that you have not read the documentation when upgrading the kernel. -- seen on c.o.l.misc
The documentation is in Japanese. Good luck. -- Rich $alz
Various documentation updates and bugfixes (the best way to know that a stable kernel is approaching is to notice that somebody starts to spellcheck the kernel - it has so far never failed) -- Linus Torvalds in the annoucement for pre-2.1.99-3
Arnold's Laws of Documentation: (1) If it should exist, it doesn't. (2) If it does exist, it's out of date. (3) Only documentation for useless programs transcends the first two laws.
The truth is not free. It's that simple. If you change the truth, it is no longer true - so the truth is not free! -- Jules Bean about freeness of documentation
When a float occurs on the same page as the start of a supertabular you can expect unexpected results. -- Documentation of supertabular.sty
What they say: What they mean: New Different colors from previous version. All New Not compatible with previous version. Exclusive Nobody else has documentation. Unmatched Almost as good as the competition. Design Simplicity The company wouldn't give us any money. Fool-proof Operation All parameters are hard-coded. Advanced Design Nobody really understands it. Here At Last Didn't get it done on time. Field Tested We don't have any simulators. Years of Development Finally got one to work. Unprecedented Performance Nothing ever ran this slow before. Revolutionary Disk drives go 'round and 'round. Futuristic Only runs on a next generation supercomputer. No Maintenance Impossible to fix. Performance Proven Worked through Beta test. Meets Tough Quality Standards It compiles without errors. Satisfaction Guaranteed We'll send you another pack if it fails. Stock Item We shipped it before and can do it again.
"I find this a nice feature but it is not according to the documentation. Or is it a BUG?" "Let's call it an accidental feature. :-)" -- Larry Wall in <6909@jpl-devvax.JPL.NASA.GOV>
The following two statements are usually both true: There's not enough documentation. There's too much documentation. -- Larry Wall in <199709020026.RAA08431@wall.org>