- From comment to paragraph
-
Writing a sentence and making these sentences into paragraphs has become my preoccupation ever since I read “On Writing Well – The classic Guide to Writing Nonfiction” by William Zinsser. Delivering a good paragraph is like preparing a dish. If successful it might be tasteful. The paragraphs constitute a logical entity of any written document. The document and the context in which it is generated is called a frame.
Though the word “frame” sounds outlandish compared to the word “context” I use it due to my professional assignment. In the Information Technology we abuse yet another word, that is “framework”. It signifies a well defined context where a task is performed. That framework is like a fully equipped kitchen with all necessary tools and ingredients to prepare a dish. What I don’t have is a precise guide on how to do it. The final result of my work (the dish) will be tested against the tastes of a wide table committee.
My reading of William Zinsser’s guide coincided with a one week holiday in Alps where I took some photographs. I slipped them in between the lines to add some colour to the reading.
- Choice of a language
-
English has become my working language ever since I integrated an international service company in France. Information Technology and banking sectors are the areas covered by my activities. And it’s an English speaking planet. Nevertheless throughout daily activities I use predominantly French and Polish; Polish essentially for talking to my French born and raised children. The oral communication on my professional assignments is overwhelmed by the local culture (French) but its written aspect has become English or when failed “franglais”. That’s why writing well in Shakespeare’s language has become a necessity.
-
Editing in a language that is not yours is a very sensible affair. Especially if I try to give a piece of a good advice on how to do it. No excuses from my side may justify any linguistic inadequacies and by attributing certain amount of indulgence from your side you will make me a favour.
If I wrote this page in French it wouldn’t change much even though France is the country that opened its gates for me more than twenty years ago. I accomplished all my education in Poland and there is always something strange in my style that a native speaker detects. If I wrote in Polish I would lose a wider public.
-
As suggested by a very old proverb, it’s never too late to learn. I already noticed that I’ve become more sensible on many points exposed by William Zinsser and though his book was intended for English native speakers I find that his message is appropriate to anybody, be it French or Polish or of any other origin. With his all present humour and a style to envy I learned how bad was I in writing. I will certainly progress through frequent rereading of his chapters as there is something that I didn’t find in E.B. White’s “The Elements of Style”. There is a “cuisine” in his book - as the French say it. It reminds me of a “cookbook” that I first read to acquire a practical knowledge of data base management.
- Where the writing is situated
-
There is much non fiction writing in the universe of Information Technology. These “books” are not a thrill not to say dull. But with certain effort we may smooth the edges and contribute to the general satisfaction. They cover three following themes:
* Technical documentation
* Messages writing
* Programmes writing
- Technical documentation and programmes writing
-
Requirements and specifications documents engage client and his potential provider in a two way communication. Client’s demand is expressed by the requirements document. Provider’s response is included in the specifications. When an accord is reached between two parties the provider launches a construction process. In Information Technology the bulk of this task is done through programming using formal languages as opposed to the natural ones like the one we use to talk.
-
Lack of precision and clarity in requirements and specifications leads to construction failures. We may build a fly instead of an aeroplane or we may deliver a plane that takes off only once. Writing a programme follows the same general tenet. It must be well written. Though the existing rules of writing them are very strict and the instruction guides abound many of them are very bad written. They are difficult to understand by other professionals and a number of missteps leads to many unexpected anomalies that we call bugs.
-
When I started as an APL programmer I learned one thing that marked my style of code writing for ever. Before you start a single line of codes write first in a good French what is expected from the object that you’re creating – taught me one of my experienced colleagues. It’s called writing comments. Programmes are lines of formal expressions that tell computer what to do. They are instructions. Even if the instructions are properly and logically written they are hard to interpret. In order to lighten that constant effort of interpretation the programmer inserts lines of comments. Thus instead of laboriously reading lines of codes you may read the explanations and understand what’s going on.
-
What my experienced friend suggested is that I should write comments first and not the instructions, and when the process is done I should check with the specifications document if all items are included. The programmes written this way would do no harm to the computer. They are perfect and no bugs may occur. The computer simply ignores the comments. It’s like taking a walk through the rooms of an empty apartment. When we check that all rooms are in place we add the furniture - instructions based on comments.
-
These comments enriched by programmer’s remarks, while elaborating instructions, are useful for writing technical documentation. Special utility tools are capable to read the programmes and pick the comments that are inserted into Word documents for further adjusting. If the comments are well written the process of adjustment is shorter. Much of the company’s knowledge is in these comments.
-
It happens that there are no comments or that the comments are unintelligible. A lot of engineers besides developing programmes develop a strong aversion to writing documents. Writing a valuable comment is as difficult as writing a good line of codes. It reminds me of certain tests given to candidates when recruited by companies: write in three hundred words on a specific issue.
-
Many times I was surprised to find my own comments vague and requiring a considerable effort and time to understand. In the same way as we can use simple tools to read the comments there is a way to automatically write comments into the programmes. Deleting comments is just a possibility.
Certain companies lost them and even all source of programmes leaving behind what we call binary codes or dry as dust lines of codes. So when there is a need for a change, even a tiny adjustment, enormous resources are engaged to implement a new, required item. A word of explanation is needed about the binary codes. What a programmer writes is a sequence of instructions called the source codes. Comments make part of it. To execute the instruction a computer must transform these sources into the sequences of “ones” and “zeros” that we call binary values. Binary because there are only two values possible: “1” and “0”.
-
If we provide the binary codes to the computer it will execute faster as no time is wasted on interpretation of the source code. That’s why in most cases we don’t need the sources to execute them. Only their binary representation are used. But if we lose the sources we have a hard time to understand what the programmes do. With some reengineering tools we recreate the source codes but we never get the comments. How they and the sources disappear is another issue. There is so much knowledge in the texts (sources and comments) that there is a good reason to protect them. Protection and safeguard is a sensible issue. Fraudulent abuse of access to the sources gives a headache to managers.
- Messaging
-
Exchange of information between the experienced members of the company through a messaging system (e-mails) is an efficient mean to implicate all persons to find a solution to an existing problem. In certain cases it’s even more appropriate than a conference call as it generates a written track of what’s being said. The collection of questions and responses constitutes a dossier that leads to making a point for a given pending issue. There is always an initiator of the issue who, based on the collected information, creates a conclusive document. Certain actions like taking a decision, implementing a solution or choosing a provider, are undertaken as a consequence of the process. Needless to say that a good written expression is essential.
- Company’s bottom line
-
There are Information Systems and solutions dating as far as thirty years old. More than ten years old is a frequently encountered case. For certain solutions an editor (external provider of the solution) assures a regular update (modifications) for others the editor has vanished. Thus the company’s knowledge implemented into existing and running solutions is very hard to extract if through years of evolution and adjustments not enough effort has been done to assure an adequate and well written documentation. All reengineering programmes that aim at replacing the existing solutions are considered as ones of the most expensive investments that a company faces.
-
If a programmer writes as valuable comments as the lines of codes the bottom line will look lighter. With a tendency to automatically generate lines of codes a new type of a programmers is needed. The one who writes good sentences with subject, verb and object in appropriate places and with a clear idea in head that if there are two sentences the second must follow the first one.
-
On one of my assignments I indicated that a list of pending issues that gives items to be resolved was unintelligible. Project leaders with years of experience who wrote them would never pass the acceptance test if they applied for the company’s position.