Black Swans and Wormhole Wizards

It is a fact that albums released by Joe Satriani are good. Or no albums by this virtuoso guitarist is bad.

The latest album, Black Swans and Wormhole Wizards, is simply perfect, melodious, and technically excellent. Right from Premonition, through keyboard laden Pyrrhic Victoria, bluesy Littleworth Lane, rocking Light Years Away, and The Golden Room with an Indian sound, the album is a listener's pleasure. Like all his previous albums, the songs are simply beautiful, but more world music oriented stuff with a tinge of dance music thrown in the right measure. The album is an intelligent shift towards international music, and drifts away from the 80s harder and heavier sound.

If I compare Black Swans and Wormhole Wizards with his previous stuff such as Surfing With The Alien, Flying In A Blue Dream, and The Extremist, then I feel disappointed. Gone are the lighting fast solos, power chords, and exploding riffs. Satch is no more a metal-friendly act. He has abandoned the "metal wave" sound that drew guys like me to him. For metal guitar, I need to look somewhere else. May be Malmsteen might save the day for me.

Walk in, Walk In, or walk-in?

Is it Walk in, Walk In, or walk-in?

The word, walk-in, appears as a noun and an adjective in Merriam Webster online.  I could not find the word without the hyphen. The Oxford Advanced Learners Dictionary website showed the hyphenated word only.

As you know, the word means someone who walks in to a place without an appointment. Typical examples are walk-in customers for a bank, walk-in interviews for fresh graduates, and walk-in patients in a hospital.

Editing Technical and User Documentation

As technical writers, most of us get a chance to review documents prepared by colleagues or writers from other teams. While a few may be reluctant to do reviews, it is a fact that the reviews provide technical writers with an opportunity to participate in the quality control process of user and technical documentation.

If the team has a technical editor, he or she may be left with enough time to do a thorough review of documents. A process will be in place to plan and complete editing. If one of the team members take up the taks of editing, the edits mostly will be a mix of “copy-editing” and “technical editing". A“production edit” can also be done on the draft versions of the PDFs created to ensure that everything is all right before it is send to the customer. The limiting factor indeed is time.

The first step in editing is to read the entire document once. It is indeed a quick read just to get an idea of what is it all about. Such a reading does give me an idea about what can possibly be the editing effort required and the complexity of the edit. On most occasions, I have been successful in marking one or more glaring issues.

In the second phase, start reading the document word by word and line by line. I begin by marking the typical copy-editing stuff using the track changes in Word or FrameMaker or as sticky notes or comments in Acrobat Professional, or even in emails. The copy-editing errors looked into include spelling, grammar, punctuation, usage, style, and writing consistency. I tread carefully on spelling mistakes because I do not want to miss spelling errors borne out of a mix of English styles such as UK English and US. I put comments as well as suggestions where the usage, grammar, and punctuation used are mixed up. For example, a comma before the conjunction “and” in a list.

Other issues focused include the voice and the tense used. Paragraphs often have sentences written in active and passive voices. I often feel that some sentences look better in passive voice, rather than in active voice. I keep an eye on sentences that suddenly shift tenses from the present to the past and even to the future for unknown reasons. I also ensure that the author follow a consistent style across the document, including the capitalization used, the terminology used, the length of sentences, and so on. Sentence construction is always a tricky issue. Paragraphs are checked to ensure that multiple ideas are not stacked, but spread out in multiple paragraphs.

Beyond copy editing, I specifically look for sentences that are technical, speak the SME's language and not the user's languages, filled with jargon, and ambiguous. The technical nature of the text and badly constructed sentences create lots of cruft. The result is the user finds it difficult to comprehend the meaning and the idea. A documentation bug is the result in such a scenario.

In other cases, there is less focus on context, but more on procedural tasks. As a result, the reader will not know what a particular feature is about, why he or she should do it, and what exactly can be achieved. Clearing these issues, at times, involve talking to the author or referring to documents such as requirement specs and design documents. In such documents, I put suggestions to rewrite the paragraphs or sentences for clarity. Compromise is the mantra.

At times, another strategy employed has worked wonders while editing. This is to log in to the application and match the procedures in the documents with the application (I know this will not work for complex software and hardware). Such a strategy helps me in ensuring whether crucial elements or steps of the work flow are missing from the documentation. It can be a field, a menu, a drop-down item, or buttons, or a shortcuts, related tasks, and so on. A technical editor can also look into issues such as the mismatch in documenting the names of GUI elements, dissimilarity between the screenshots and procedures, screen names, the tab flow of fields (if present), mandatory values, lack of troubleshooting tips, and so on.

I also look into the template issues, formatting, and layout. Currently, this involves correct use of character and paragraph tags and master pages, heading styles and hierarchy. On PDFs, I also check whether cross-references work and whether they land on the page intended. I do comment on the overall layout: topics starting at the end of the page, orphan sentences and bulleted lists, and pages starting with screenshots and notes and warnings, procedures without intros. I also check the white space present in pages and the proportion of body text and graphics on a particular page so that the “weight” is balanced.

I like words and like to review definitions of terms. While a few can be verified using the internet, on many instances, I need to discuss them with the authors as well as the experts.

I check the organization of the document. Instead of topics organized to relate to each other, topics may look disparate and incoherent. They may lack unity among various sections of the document. It simply means the whole will not be the sum of its parts. Typically, I will try to ensure that writers do not miss the crucial aspect of ensuring a flow so that the information is rendered not usable. If a casual reader cannot find the information easily, imagine the plight of the user who is busy to finish the task. I love cross-references in te documents. I feel the absence of adequate cross references thwarts the unity of the document.  If I enter a few details, I should know how to verify that information. Documentation and its architecture sometimes miss this crucial element.

Finally, I just close the document and come back to it later to review my comments. I do this to ensure that I have missed anything and I have not done any hyper-editing.

For me, copy-editing or technical editing is not nitpicking. It is not an act to put someone on the defensive. It is a quality control process to ensure delivery of good and quality documentation to customers. It is also a learning process for me, as I need to be first sure that my concerns are right, and my findings are valid. It is not necessarily that I am always right. The author can also be right and I can learn from him or her. It is a collaborative process to ensure that the efforts fulfill the wider objectives set for.

Copy editing in Newspapers

How different is copy editing from the editing you do as part of your technical writing? Some might feel that it is nothing compared to what is done in technical writing. Others might say a lot can be carried from newspaper copy editing to technical editing. Others might say both are miles apart.

I can't help from saying that there is an awful lot of misunderstanding about a copy editor's work in newspapers. On the internet, one of the best quoted or linked source of what a copy editor does is at The Slot. Click here to read The Slot's article on What Exactly is a Copy Editor.  Here, I don't intend to pass judgements on which one is more challenging and complex, or which one is easy.

Let me put my perspective what a copy editor (sub editor in Indian parlance) does. Firstly, it is neither a "mere" editing job, nor a proofreading job. It is job with lots of responsibility, pressure, and requires syncing with the editorial team, the reporting team, the graphics team, advertising, and even the sales and marketing team.

A copy editor, as a journalist, needs to know something about everything under the sun. Knowing everything means learning new subjects and keeping track of the happenings in the English language and the profession. (Unlike in the media, a technical writer can focus on the particular domain or tool based on his or her job requirements. He or she is not supposed to know each and every domain).

When a copy editor walks in and logs into his or her machine, there will be nothing on the "queue" to edit. Stories filed by reporters, correspondents, senior journalists, start to flow in slowly, often late in the evening. Of the stories that come in, one has to be selected as the lead or main story. A lead story appears more prominent on the page, usually at the top left or right, spreads across many columns, and is set in the biggest headline style. Editing is based on the house style and the copy editor has to keep an eye on the legal implications of stories.

While most of the day is spent on editing news stories, an hour or more is left to design or make pages using a software like QuarkXPress. A copy editor usually makes more than one page. It is here that the skills get really tested.

The reason is the page. A copy editor does not have any control of the preliminary design of the page. You can consider the page as the template we often talk about in technical writing. Typically, a page is divided into 7-8 columns. This template is initially drafted by the "ad" department. Pages will have ads, which take a few columns at the bottom of the page, or half the page. The more the ad space is, the more happy the copy editor is. This means that the "template" a copy editor works on is never the same. A copy editor actually works on widely different templates daily.

The templates are different, but the deadline is the same. The templates are different, but the level of edits required for stories are different. Moreover, every page requires photos to balance the weight on the page. And if the ad department comes with a last minute change, you can imagine the pressure and the mess the copy editor can be in.

The newspaper industry is the only industry that releases a new product every day. In the mornings, you read the news edited by copy editors and view the pages designed by the copy editors last night.

Engaging User Documentation

One of the words that technical communicators should have in their vocabulary is Engage. Because the word also means to "become involved." In reality, many technical writers refuse to get "actively" involved with the project teams and refuse to accept responsibility for mistakes on their part. A few even consider
themselves as "individual contributors" in a team.

Technical writers cannot sit before the desktops and imagine that everything—information, reference documents, software build, and so on—will reach them automatically. They cannot simply shift the blame for incorrect information or missing information in their documents to someone else. For technical writers of any level, engaging themselves with the project team is the most crucial aspect. This may require lots of legwork, casual chat, and intent to even befriend a few team members.

The primary benefit of such an interaction is more or less complete documentation of the software and feature developed. Even though project managers may not be that keen to interact with technical writers, there are others with whom the technical writers can get involved. It is this healthy involvement of technical writers with software developers, testers, and SMEs that will enhance the reputation of the technical writer and improve the understanding of the work a technical writer does. Technical writers would also benefit in understanding the functionality properly and get a holistic view by engaging fully with the team, and not just with the SME.

This kind of "internal networking" will benefit a technical writer in multiple ways. As mentioned earlier, a good engagement works wonders for preparing a complete and proper documentation. It also helps the technical writer to understand the software and the domain in a better manner. It also drives a technical writer to provide feedback, ask questions from the user perspective, and even don the role of a tester at times. Some of the feedback or queries raised can even become a critical issue or priority task for the development team.

A successful engagement will gradually increase the flow of information to the technical writer. People, who earlier refused to divulge information, will open up and provide tidbits of information that will aid the technical writer to write better documentation. For those looking for everything to arrive at their desks, technical
writing is not the best profession.