Month: June 2012

My Experience as a Technical Writer

Time has changed, not reality. 

“Put It In Writing-But Clearly — Software makers should help writers and artists create user manuals that are easy to understand”

BYLINE: Joel Solkoff

SECTION: FINAL WORD; Pg. 95

LENGTH: 728 words

When I left Washington nearly five years ago to take an exciting position in high-tech Research Triangle Park, N.C., many friends told me horror stories about the manuals they had received with software.

My new job was in telecommunications. I thought that because I was writing user manuals for expensive computerized switches, my employer would want me to make the manuals understandable. I was mistaken.

More recently, I worked on an object-oriented software development project. My job was to read the documentation the software designer had produced and rewrite it in plain English so that technicians in the field could understand how to load and use it.

“Don’t Bother”

I was told, however, that if I actually took the time to read and rewrite the documentation, it would delay production of the product manual. There had been little attempt to plan the process to ensure timely delivery.

Instead, management resorted to exhortations: Don’t bother to read about each product feature, just cut and paste from the software designer’s information. And don’t waste valuable time rewriting.

Technology suppliers today are under great pressure to rush new products to market. As a result, the way documentation is produced may cause these companies serious problems. Vendors that make complex software and hardware products should make the products as easy as possible to use. In some cases, such as sophisticated telecom switches, these products may compete with technology that is less sophisticated and that requires little documentation.

Producing decent documentation is not difficult. There are only a few steps to follow: Ask the customer what is needed. Produce it. Test it. Ask the customer if the documentation meets the requirements.

As simple as this process is, it is seldom followed. Computers and communications equipment buyers are told what they will get. An occasional, unmethodical survey is conducted to support the product manager’s choice of documentation. Useful modern marketing techniques such as focus groups seem beyond the ken of companies intent only on getting something out the door.

In addition, writers are often asked to translate unintelligible techno-jargon without first talking to the software designers, all because the designers aren’t allocated the time to make a discussion possible. Editors often don’t know enough about the subject matter to ask the questions that would make the documentation more understandable.

Diagram artists also complain about how poorly their skills are used. A recent editorial in Computer Artist lamented “relentless production schedules that often do not allow a reasonable amount of time to think about the art and the message it conveys.”

Finally, many product managers make the mistake of not even bothering to read the documentation that accompanies the products they worked so hard to produce.

These problems exist whether documentation is produced as printed manuals or in electronic form.

Contracts Over Customers

The big question is whether, in a period of cost-cutting, technology companies are willing to pay the price of educating their employees about the products they sell.

The second question is whether the companies even know how to do so. To cut costs, many are switching to contractors for their documentation. Technical authors work for agencies that contract with the company and farm out the work. These agencies could take responsibility for the manuals they produce, but their primary focus is on getting new contracts, not customer service.

Our high-tech businesses thrive on complexity. But unless they improve the quality of their documentation, they may endanger their ability to continue selling the sophisticated products that distinguish them from the competition.

Given the choice between a product that works intuitively and one that has difficult-to-read, often incorrect documentation, many customers will make the obvious choice.

–30–

Joel Solkoff is [was] a senior technical writer in Durham, N.C. Published July 3, 1995

Final Word [the section of the magazine in which this appeared] is a forum for professionals with opinions on information management. Your contributions are welcome. IW cannot return unsolicited manuscripts. Please send submissions to: InformationWeek, 600 Community Drive, Manhasset, N.Y. 11030


Hear Lytton Strachey’s Eminent Victorians

Lytton Strachey was a member of the Bloomsbury Group http://en.wikipedia.org/wiki/Bloomsbury_Group. Strachey (1880-1952) may have been the first "modern" biographer by which I mean: sardonically humorous, an intense researcher, a firm believer in his own idiosyncratic get-to-the-point-and-stick-with-it elegant writer. Virginia Woolf's sister Vanessa Bell painted this portrait in London in 1911 (available through Yale University's Digital Resources Collection).

Click in this link to hear Strachey’s brilliant hatchet job on Florence Nightingale:

http://ia601209.us.archive.org/6/items/eminent_victorians_1204_librivox/eminentvictorians_11_strachey.mp3

Why do I do what I do? Specifically, why am I making available on my website [hidden in the Blank Verse category (erroneously named)]: the work of Lytton Strachey virally available elsewhere if you care to perform a Google search (if you care)?

Why now?

Lytton Strachey was a member of the Bloomsbury Group http://en.wikipedia.org/wiki/Bloomsbury_Group. Strachey (1880-1932) may have been the first “modern” biographer  which, in his case, includes being: sardonically humorous, an intense researcher, a firm believer in his own get-to-the-point-and-stick-with-it elegant writer. Virginia Woolf’s sister Vanessa Bell painted this portrait in London in 1911 (available through Yale University’s Digital Resources Collection).

The link above is to a LibriVox recording of Eminent Victorians by Giles Lytton Strachey read by Margaret Espaillat.

Table of Contents
  • 20:121 01 – Preface and Cardinal Manning, Chapter 129:022 02 – Cardinal Manning, Chapter 2
  • 39:553 03 – Cardinal Manning, Chapter 3
  • 33:054 04 – Cardinal Manning, Chapter 4
  • 37:155 05 – Cardinal Manning, Chapter 5
  • 37:206 06 – Cardinal Manning, Chapter 6
  • 37:257 07 – Cardinal Manning, Chapter 7
  • 13:328 08 – Cardinal Manning, Chapter 8
  • 10:229 09 – Cardinal Manning, Chapter 9
  • 13:5010 10 – Cardinal Manning, Chapter 10
  • 14:0011 11 – Florence Nightingale, Chapter 1
  • 49:0212 12 – Florence Nightingale, Chapter 2
  • 54:1713 13 – Florence Nightingale, Chapter 3
  • 29:1314 14 – Florence Nightingale, Chapters 4 & 5
  • 36:3815 15 – Dr. Arnold, Part 1
  • 37:2616 16 – Dr. Arnold, Part 2
  • 34:3717 17 – The End of General Gordon, Part 1
  • 28:4118 18 – The End of General Gordon, Part 2
  • 30:0219 19 – The End of General Gordon, Part 3
  • 29:4620 20 – The End of General Gordon, Part 4
  • 35:1121 21 – The End of General Gordon, Part 5
  • 36:2422 22 – The End of General Gordon, Part 6
  • 35:2023 23 – The End of General Gordon, Part 7
    “Sometimes referred to as the Nightingale Jewel, this brooch, the design of which was supervised by Prince Albert The Prince Consort, is engraved with a dedication from Queen Victoria, ‘To Miss Florence Nightingale, as a mark of esteem and gratitude for her devotion towards the Queen’s brave soldiers, from Victoria R. 1855.’ The brooch was not intended to serve merely as a piece of jewellery, but rather, in the absence of a medal or established decoration suitable for presentation to such a female civilian, it stood as a badge of royal appreciation.” –National Army Museum, London
LibriVox notes:
“On Modern Library’s list of 100 Best Non-Fiction books, “Eminent Victorians” marked an epoch in the art of biography; it also helped to crack the old myths of high Victorianism and to usher in a new spirit by which chauvinism, hypocrisy and the stiff upper lip were debunked. In it, Strachey cleverly exposes the self-seeking ambitions of Cardinal Manning and the manipulative, neurotic Florence Nightingale; and in his essays on Dr Arnold and General Gordon, his quarries are not only his subjects but also the public-school system and the whole structure of nineteenth-century liberal values.”
[Note: I first read Eminent Victorians in 1972 at one of those moments I have had in  life where I was recovering from a disaster. The disaster in this case was my first divorce after my wife left me for a taxi cab driver in New York whom she met at an evening class in Chemistry. My reaction was to follow my friend David Phillips’ suggestion and move to San Francisco where we lived as roommates in a wooden red house in the Bernal Heights section–an area so steep that when I left the house to pursue free-lance writing assignments and women, I had to walk sideways.
Bernal Heights, a San Francisco neighborhood, where I lived close to the peak and could see from my desk in the front room (assuming no fog) the Golden Gate Bridge across the expanse of the City.

[In times of stress, I turn to literature. One day David handed me Eminent Victorians saying,  “This was written by the man who invented the New Yorker profile.” I went on to read Strachey’s biography of Queen Victoria and became immersed in the Bloomsbury Group, especially Virginia Woolf and eventually the multi-volumed autobiography of her husband Leonard. Strachey’s words especially were a great comfort, reading someone who could write so well and leading to the fantasy that someday I might acquire that ability.]

 

Today is Bloomsday

Next year, Webster’s proprietor Elaine Meder-Wilgus will be reading the role of the sensuous Molly Bloom whom Joyce deliberately paralleled to Homer’s Penelope.

State College, PA, June 16, 2012, across Beaver Avenue from Webster’s Bookstore and Café where next year [not in Jerusalem, but at Webster’s] Bloomsday http://en.wikipedia.org/wiki/Bloomsday
will be celebrated properly]:

Next year, Webster’s proprietor Elaine Meder-Wilgus will be reading the role of the sensuous Molly Bloom whom Joyce deliberately paralleled to Homer’s Penelope.

“Stately, plump Buck Mulligan came from the stairhead, bearing a bowl of lather on which a mirror and a razor lay crossed.”

This is the first sentence of Ulysses, James Joyce’s novel, first published in 1922 and for 15 years banned in the United States as obscene.

U.S. Postal Authorities prevented its distribution in one instance burning 500 copies.

The Committee on College Reading, endorsed by the National Council of Teachers of English and the American Library Association, recommends Ulysses as one of the 100 most significant books in the world.

Today, Joyce’s novel about one 24 hour-day in Dublin, June 16, 1904, is being read aloud throughout the world–all 265,000 words.

Depending on the size of the print, as many as 1,000 pages are being read out loud today, including here in Pennsylvania where Philadelphia’s Rosenbach Museum and Library houses the famous first edition published in Paris by Shakespeare & Company.

Today, say No to banning books; Yes to great literature; Yes again with Molly Bloom as she says in the last words of Ulysses, “…yes I said yes I will Yes.”

http://en.wikipedia.org/wiki/Ulysses_(novel)

James Joyce

+++

“Twenty years have passed,” writes the authoritative Joycean critic Stuart Gilbert in 1950, “since the appearance of the Study of Ulysses of which this is a new…edition…and among many notable events of these two decades one of the most interesting, from the literary point of view, was the lifting of the ban on the admission of Ulysses into the English-speaking counties. In the original Preface to my book I said: ‘In writing this commentary I have borne in mind the unusual circumstance that, though Ulysses is probably the most discussed literary work that has appeared in our time, the book itself is hardly more than a name to many….”

Consequently, in his discussion of the novel, which at one time was so hard to obtain that New York University’s smuggled copy was chained to a table in the main library lest it be stolen, Gilbert provides extensive quotations. In the last chapter entitled Penelope, the name Homer gave to Ulysses’ famously loyal wife, Gilbert discusses Molly Bloom’s soliloquy that ends the novel.

Gilbert writes,” [T]he force of this long, unpunctuated meditation, in which a drowsy woman’s vagrant thoughts are transferred in all their named candour of self-revelation on to the written record, lies precisely in its universality….”

Gilbert continues, “The concluding pages, a passage of vivid lyrical beauty…are at once intensely personal and symbolic of the divine love of Nature for her children, a springsong of the Earth; it is significant for those who see Joyce’s philosophy, nothing beyond a blank pessimism, an evangel of denial that Ulysses ends on…a paen of affirmation.”

Gilbert then quotes Joyce’s Molly Bloom saying to herself:
I love flowers Id love to have the whole place swimming in roses God of heaven theres nothing like nature the wild mountains then the sea and the waves rushing them the beautiful country with fields of oats and wheat and all kinds of things and all the fine cattle going about that would do your heart good to see rivers and lakes and flowers all sorts of shapes and smells and colours springing up even out of the ditches primroses and violets nature it is as for them saying theres no God I wouldnt give a snap of my two fingers for all their learning….yes I said yes I will Yes.”

++++

Listen now to  Marcella Riordan read the last 50 lines of Ulysses as your heart thumps with joy.

http://www.youtube.com/watch?v=_sEOK0En6Pk

++++

Joyce selected June 16th as the 24-hour day during which all the action in Ulysses takes place because it was the date of his first date with Nora Barnacle who became his wife and was always his muse.

++++

This surprisingly sexy, mind-opening book by my one-time editor Brenda Maddox is terrific.

[Aside, in 1984, my friend Jonathan Miller, as I was about to leave for China, told me he would publish an interview on the telecommunications plans of the Beijing Ministry of Posts and Telecommunications if I could somehow get an interview. Jonathan and Brenda were editing a joint D.C. Telecommunications Daily/London Economist publication. When the interview turned into a series of articles, Brenda was an excellent editor. At the time, Brenda was also working on this biography of Joyce’s wife, long regarded by distinguished Joyce scholars as an extremely dull woman. Jonathan had read the book proposal, envied the size of the advance (as did I), and marveled at Brenda’s ability to track down erotic letters between Nora and James Joyce. When I finally read Brenda’s book, she was able to open up Ulysses for me in a way that finally opened up the pleasure of reading the great novel which had previously seemed so intimidating. ]

This is how Amazon describes:

Nora: The Real Life of Molly Bloom

http://www.amazon.com/Nora-Real-Life-Molly-Bloom/dp/0618057005

Publication Date: June 16, 2000
“In 1904, having known each other for only three months, a young woman named Nora Barnacle and a not yet famous writer named James Joyce left Ireland together for Europe — unwed. So began a deep and complex partnership, and eventually a marriage, which endured for thirty-seven years.
“This is the true story of Nora, the woman who, transformed by Joyce’s imagination, became Molly Bloom, arguably the most famous female character in twentieth-century literature. It is also the story of Ireland, a social history encapsulated in the vivid recreation of Joyce and his small Irish entourage abroad. Ultimately it is the portrait of a relationship — of Nora’s complicated, committed, and at times shocking relationship with a hardworking, hard-drinking genius and with his work.
“In NORA: THE REAL LIFE OF MOLLY BLOOM, the award-winning biographer Brenda Maddox has given us a powerful new lens through which to see both James Joyce and the woman who was in turn his inspiration and his salvation.”
++++
Next year, Events Coordinator Molly Haight will be working with the Director of 2013 Bloomsday at Webster’s.

Molly is currently accepting email applications for the position of Director of 2013 Bloomsday at Webster’s at the following address:[email protected]

We are looking for a faculty member in the English Department at Penn State sufficiently familiar with the 18 episodes of Ulysses who will:

  1. Provide audiences with a brief overview of each episode before reading begins
  2. Organize the readings
  3. Recruit readers
  4. Designate a preferred edition so readings can take place smoothly
  5. Be prepared for the gratitude and adulation of the Webster’s literary community
At next year’s Bloomsday celebration, Cafe Manager  Meg McAuley will be dancing to your table with Irish tea and real Pennsylvania cream plus lots of wonderful Irish soda bread. Special orders for kidneys will be taken at the appropriate time.

Right now, Robbie Mayes has just received a shipment of James Joyce scholarship, really juicy books.

Next year, film lecturer Anne Triolo will be in charge of all video arrangements. You saw her win on Jeopardy, imagine what she will do in her own metier.

Until “met him pike hoses” (metempsychosis) [“Yes. Who’s he when he’s at home?”], watch this selection from the 1967  movie Ulysses:

http://www.youtube.com/watch?v=uQcrVND-N8o

Webster’s on the web:

http://www.webstersbooksandcafe.com/

Webster’s on the map:

https://maps.google.com/maps?hl=en&ie=UTF-8&q=webster’s+state+college&fb=1&gl=us&hq=webster’s&hnear=0x89cea899c13bdb73:0x9ce1c6c2833c8091,State+College,+PA&cid=0,0,4409987300851388285&ei=pB_dT8HkAoSE8QT-roH_Cg&sqi=2&ved=0CA4Q_BIwBQ

This is how Bloomsday is observed in Dublin.