The Laws of Programming

1. If it's a stupid design but it works, it isn't stupid.
2. No code ever survives its first draft.
3. There is no such thing as perfect code, unless you are talking about "my" code in the common library.
4. Important things are simple; and simple things are always hard.
5. Anything you program can go wrong, including nothing.
6. For every programming style, there is an equal and opposite criticism.
7. When reviewing the code snippets that you wrote down on a scrap piece of paper out of the office, the most important ones are always illegible.
8. Stealing code is called plagiarism. Stealing code from a smarter Programmer is called innovative and smart.
9. There is always a way to code something, and it usually doesn't work.
10. If only one solution can be found for a coding problem, then it is usually a stupid solution. (See rule #1)
11. Any given program, when running, is obsolete.
12. If a program is useful, it will have to be changed.
13. If a program is useless, it will have to be documented.
14. Program complexity grows until it exceeds the capabilities of the programmers who must maintain it.
15. Adding manpower to a late software project makes it later.
16. The only truly original algorithms were by a time traveler who stole them from the future.
17. The better the program, the more it will make the user want a better program.
18. Temporary test code will always outlast 'real' code and cause untold damage in the future.

Failure:

FAILURE IS NOT AN OPTION! It comes bundled with every copy of our software.

Help Files:

Most computer "help files" should be called "unhelp files"

If all else fails, stop reading the manual, you'll do much better that way.

Serious (yet, tragically funny) comments:

A user was lamenting that a software manual was so riddled with errors that it was easier to use the software by ignoring the manual. She also explained that whoever wrote the manual didn't think about how the software would be used, just how it was written. I explained to her that unfortunately, this is the normal case for computer manuals. I wish it weren't a joke, but it is true that Manuals typically document:

1. The way the software was supposed to work OR
2. The way someone who tried the software once THOUGHT it worked OR
3. Someone goes through each screen, documenting each field with useless comments like "The Title field is the location at which you should enter the Title that you want to use. The size field is the location at which you should enter the Size that you want to use. The ...." Well you get the idea.

In the fall of 2002 an Alberta Canada Government, a software package sent to schools throughout the province came with a document:

• grandiosely titled "[name of software] Manual". (Yes, the words "name of software" and the []'s around them were exactly what was printed on the manual.)
• Inside was 1 piece of paper that listed the hardware required to run the computer! Nothing about the purpose, loading, installing or using of the software!
• Worse ... it turned out that this list of required hardware wasn't correct!
• Worse a copy of this was shipped, with the software on a disk, to every school in Alberta
• Worst: and it was mandatory that the schools use this software for their reporting!

Not a joke. Creating real manuals:

Note: I have been involved in creating "real" manuals, books and articles for "real" software. I understand that most developers, having spent way too much time and effort on the development just can't be bothered writing good manuals. In my opinion, the number 1 missing feature of most manuals is a "procedures" section. This is a section that stands back and asks:

• What are all the objectives the user will want to accomplish with this software.
• What are all the typical work flows.
• What are all the unusual (but legitimate) work flows.
• What problems might the user encounter and how should they go about solving them.

Once the software gets into alpha and beta test, every question asked by the testers should be considered in light of the above 3 questions to see if it warrants documentation this way.

The number 2 feature missing in most manuals is a USEFUL index. Most software packages will have manuals that only document using the words used by the software developers. For example, in a product that has "Automobile", so the index has an entry for automobile. But it should also have index entries for things like car and vehicle as appropriate to the software. Just because the developer used the word "Automobile" doesn't mean that the user will immediately think of looking up under automobile. Remember: If you don't immediately come up with the words your users will search by -they won't come up with your words when searching the index.

So how do you gather good words for an index? I'm glad you asked! You initially provide the manual on line only, with a search engine for finding words. You then record every word searched on, whether the word was found or not, and ask the user to reply whether the search resulted in the expected information (with a comment field for them to explain). Then you study the results, especially the "no hits" and the "well, it found the word, but that wasn't what I was looking for"s. If you can't do it the above way, you also ask your testers to record everything they looked up by and didn't find a result.

Also, all error messages should be documented in an alphabetic way (or indexed) and then key it to the procedures section.

2017 Update: Given how pervasive and easy indexing is (you can use google to search a specific site that doesn't even have an official index), I am more and more leaning towards just including the alternate word in the body of the text. So saying 'blah blah Automobile (car/vehicle) blah blah' the first time in a section I use such a term, this allows any indexing system to find it. I also sometimes run things together for exactly the same reason, so the phrase 'The Automobile' has a very specific meaning in your application, I might put (TheAutomobile) in as well, making it easier to search. I don't usually do this for 'consumer' manuals because it is confusing to explain, but for technical users I do. You still have to spend time gathering words you should use, but you don't have to build the index.

Other Short and One Liners

Computer programming often has cryptic codes that make sense only to the developer. One day I was working through some code where all variables of a type started with "T" followed by a word or phrase. In the code review we came across TReason, upon which one of the reviewers cried out "That's TREASON!"