Bad documentation says what things are. Good documentation says what they do.
The widespread contempt for grammar in society is one of my numerous hobby horses. In school I got the impression that grammar was about diagramming sentences and placing commas. They told us that certain constructs are incorrect, but these were presented as arbitrary societal rules which serve no other purpose than to demonstrate education and get into a good college. Since this was in the 1980’s and conforming to arbitrary societal rules were seen as uncool and silly, grammar was uncool and silly.
What they did not tell us was that not only do words have meaning, but gramatical constructs have meaning too and sometimes if you use the wrong one you will not be understood. This is not always a problem in the situations of daily life since most people know what you meant to say.
But computers are complicated and very flexible. The way software works can be difficult to explain and not entirely obvious. If you are writing the manual but don’t have the grammatical chops to pull it off, your readers can be left guessing. You need to explain how data moves through a system, what steps are taken in what order. You do not need to be a grammar expert, but you need to know how to express ideas clearly, so say the data “enters” something, “is collected” from some places, that it “passes through”. You need to know how to say that one thing was replaced with another without mixing up the old and the new thing.
So pay attention to grammar. Learn to use prepositions to explain where data is and where it is going. Use real verbs. Do not say that “this is the notification e-mail address”. Say “This is the e-mail address to which a warning is automatically sent when the XYZ process stops unexpectedly.” Your users will thank you and they will be more likely to stick around because they understand how your product works and how to use it.
The review as it appeared in the Literary Gazette. Caption under photograph of storm trooper: This is what one of the “heroes” of the film War of the Stars looks like.
This is the first review of Star Wars published in the Soviet Union. It appeared in the Literary Gazette, a Moscow weekly, on September 7, 1977.
It is unlikely the reviewer had had an opportunity to see the film, nor would most of her readers be able to see it anytime soon. All we learn about the plot is that the main characters engage some kind of formidable tyrants in light-saber battles. The emphasis on the physical appearance of the characters suggests that posters and production stills are the primary source. Over half the text is devoted to portraying the film as a crass commercial endeavor aimed at undiscerning viewers.
The name of the film is translated as War of the Stars, a misunderstanding which was corrected in later reviews. The first month’s box office receipts appear to be overstated. The statement that a sequel will be out in a few weeks is puzzling seeing as The Empire Strikes Back was not released until May of 1980.
Mass Culture 77 Space Horror Films By Yu. Varshavskaya
This summer American movie theaters were hit with a new wave of “movie madness”. According to the press, the film War of the Stars by American cinematographer George Lucas is breaking all box office records: $60 million profit from the first month of showings. From morning until midnight War of the Stars is shown in overflowing theaters. In order to get into the film one must either stand in line for several hours or pay a scalper a fabulous sum – 50 dollars.
And so “evil spirits”, huge disasters, and giant sharks have been replaced on the American screen by horrors of truly cosmic proportion – monstrous tyrants who terrorize our Galaxy. The battle against them is waged by the heroes of the film – a certain round-faced princess, a village youth, an elderly knight of the Round Table, an ape-man, and two robots. One of them, the enormous gilded robot Threepio, is endowed with human speech. The other, Artoo-Detoo, resembles an automobile and expresses himself in “star” beeps.
The plot of the movie, as the French weekly Express writes, is rather simplistic.
But to really frighten the locals the makers of the film have employed the most modern of weapons – a laser ray with which the heroes of the film do battle as with rapiers. Nightmarish monsters are constantly appearing on the screen: a lizard-man, gnomes without faces, a living mummy with a head with rubber tubes sticking out, fantastical animals…
At the same time as shooting of this blood curdling “masterpiece” which the cinematographer George Lucas calls “the western of the future” was going on, a number of related commercial schemes were undertaken. The publisher Ballantine released a novel under the same name. Then Marvel Comic Book [sic], a publisher which specializes in comics, signed a contract with the movie studio Fox and, having divided the script into six parts, began issuing a monthly War of the Stars comic book. The press run is a million copies. Right after that the classic accouterments of “mass culture” appeared: buttons, tee-shirts, movie posters, and soundtrack records. And the children’s toys should be in the stores in time for Christmas [literally “New Year’s”, the holiday to which the Soviets had transfered the Christmas tree and gift-giving tradition]: a miniature Artoo-Detoo which makes the very same sounds as the original, and the gilded Threepio. The biggest “find” of the film, the toy laser rapier, is not invented yet, but work has already begun.
In the next few weeks there is due to appear on the movie screens of the USA a new episode of War of the Stars which is likely to be as mediocre as it will be profitable. This is not to be wondered at. The mass audience is ready to bite at such pieces of “art” in order to, when leaving the movie theater, see that things outside are fairly quiet…
The Radio Shack stores played a big role in my childhood. My first memory of Radio Shack is from around 1975 when I was six. I went with my dad when he bought new speaker cables. We went others times whenever our TV stopped working. Dad would take the back cover off, pull out some vacuum tubes, and take them in to Radio Shack to use the tab tester. Sometimes there would be a line for the tester. If the tester said a tube was weak, dad would go over to a counter and ask the man there for a new one.
Knowledge is a slippery thing. If we don’t take care we can lose it. Organizations loose it when members leave or retire without passing it on to their replacements. Suddenly the organization does not know how to do part of its job and has to spend time and money finding out again. Sure, sometimes new blood brings fresh ideas which work better, but more often the organization just makes painful mistakes until the lost experience can be regained.
Human societies experience the loss of Institutional Memory when one generation fails to pass enough of what it has learned on to the next.
As a child in the 1970’s I watched family dramas on TV. By “family” I mean that they showed children growing up, having adventures, and dealing with situations in life which were new for them. I particularly remember The Swiss Family Robinson. The children often approached difficult situations by doing what they had seen their parents do. When things did not work out they often discussed the problem with their parents and then tried again.
These shows were entertainment, not instructional films. The writers were not primarily conveying lessons to children. They were creating dramatic tension and having their characters resolve it in the tradition of the Western story arch. Getting advice from persons with more experience (often parents) was a natural part of the story.
