Latest Articles on tcworld.info

Of power adapters and language quality assurance

Wed, 01 Feb 2012 00:00:00 +0100

In the translation industry we also see significant price variations (though, luckily, on a smaller scale) and even more serious variations in review ratings. You have to wonder: Is there a real, pressing need to measure language quality and if so, is there an objective and viable method of measuring it?

The �lemon market� trap

To better understand the QA issue within the translation industry, my colleague and Logrus co-founder Serge Gladkoff has drawn a parallel to a different market: The term "lemon" is strongly associated with the US car market, where at a certain time the quality of cars was bad enough to call for a special legislation protecting consumers. The term "lemon market" was coined by the economist George Akerlof and depicts the so-called information asymmetry, which occurs when the seller knows more about a product than the buyer. The concept in brief: As far as the buyer can't reliably measure the quality of the item (a car, a power adapter or a translation), he will assume that the item is of average quality. Hence, this buyer will only be ready to pay an average price for the item, which in turn leads to a situation where items of significantly higher quality won�t achieve a high enough price to make selling them worthwhile. The withdrawal (or marginalization) of high-quality items reduces the average quality of items on the market, causing buyers to revise their expectations downward for any given item. This, in turn, motivates the makers/owners of moderately good items not to sell, and so on. Thus, there will always be an incentive for sellers to pass off low-quality goods or services as higher-quality ones and a distinct advantage for some vendors to offer low-quality goods or services to the less-informed segment of a market. Now, let's go back to real life and start with laptop power adapters and the abovementioned user review mess. As we see, what�s happening is the exact consequence of information asymmetry, i.e. we are trying to rate the quality of goods/services without being able to analyze truly important factors. When I get a power adapter I can assume with confidence that most adapters, irrespective of their price, were assembled at an obscure factory somewhere in China. I can also check some basic things: whether it has a tip that fits my laptop, whether it works at all, and whether it overheats dramatically or dies within the next several days. My review would therefore be based on these obvious aspects. However, my scientific background tells me that I am actually missing the main point. What does really matter in the long run, regarding the quality and reliability of my power adapter? The quality (and source) of its circuitry and parts, a proper design taking into account power dissipation, the soldering (automated rather than manual to avoid future oxidation), etc. Can I measure these factors by any means under normal conditions? No! So my guess about the device�s quality/longevity will, at a closer look, remain just a wild guess. When buying the adapter I will most likely think: $7 seems to be marginally low, $50 is way too much, and most of them cost below $25, so $15 will probably get me a decent one. And I might be totally wrong, because this estimate might prove too low to get a reliable adapter made of robust parts at a clean, automated factory with full-scale quality control. This is a lemon market: average values are absolutely deceptive and I�m not choosing between good and bad, but between multiple lemons! Sounds too familiar? That's because over the last ten years the translation market has evolved exactly into a market for lemons. This is due to a number of factors, including enormous pricing pressure from clients (who are typically much bigger than vendors in a B2B market), unlimited recycling (giving a new life to erroneous or obsolete translations) and abundance of poorly post-edited MT materials, low entry cost (tempting thousands of amateurs), an incredible level of segmentation (when it becomes almost impossible for the translator to understand the context), free crowdsourcing alternatives, etc. The only difference is that we are not talking about the loss of $15 in the worst-case scenario, but about far more important implications and consequences. When considering typical feedback related to translation quality, one can�t miss another surprising parallel with power adapter reviews: While some of it is quite legitimate and substantiated, most feedback comes from in-country offices or in-house employees who happen to know the language in question, or from a randomly-chosen reviewer who was asked to take a look at the translation. Most of these people are competent in their professional area, but they are neither linguists nor translators. More than that, they are typically unfamiliar with existing terminology glossaries, unaware of inter-product compatibility or legacy-related issues, are doing their review from scratch, i.e. without any support materials or formal guidelines, and tend to introduce a strong taste-based flavor into their reviews. As a result, a significant part of the language quality feedback obtained using traditional methods produces results that may be logical, but are anything but objective. Getting back to the analogy discussed earlier, the reviewers are basing their judgment on the exterior of the power adapter and its ability to provide 19V DC alone, rather than subjecting it to a series of objective certification tests. While the �more for less� slogan has never been more popular, the sad reality is that one typically can�t get more for less without major breakthroughs, which are not too frequent. In most cases, customers quite expectedly get a �well-disguised less� for less. How can one survive with dignity on the lemon market and still buy translations of good quality? Only by eliminating this information asymmetry. In our case this means getting professional, thorough and objective, independent language quality reviews that bring both confidence and peace of mind and help avoiding costly errors.

What is Language Quality Assurance?

Language Quality Assurance (LQA) refers to the assessment of the linguistic quality of materials based on international and industry-wide standards as well as the client's standards, requirements and guidelines. Primarily, this relates to two things: terminology and style on one hand, and quality metrics and criteria on the other. The idea that any translator or editor can become a reviewer overnight is an illusion, and a dangerous one. Such instant conversions provide the unprofessional reviews discussed earlier. In reality a lot of specific training is required, as well as a specific mindset. A reviewer can�t fix errors or improve whatever he finds necessary. Instead, he has to:

Follow a complete set of formal rules
Use formal feedback forms correctly
Follow very specific and often rather peculiar guidelines for each job, as LQA requirements and guidelines might differ for various clients
Apply strict evaluation metrics, and suppress all emotions
Either ignore or impose style-related considerations depending on the client�s requirements
Conduct reconciliation discussions with the translator

It�s worth mentioning that LQA is not supposed to improve materials or fix errors. It is simply expected to give us a reliable estimate of how good or bad the materials in question are. Despite this trivial definition, we�ve come across multiple cases where client expectations related to LQA were quite different:

The most common belief is that LQA will not only assess quality, but also fix problems, which is actually a hybrid of LQA & editing. Editing to LQA is like treatment to diagnosis. You first need to make a good diagnosis, and then start the treatment. The combination of LQA and editing is only viable short-term, but will not work as a permanent solution because if one vendor translates materials, and the other performs QA and editing, then there is no hope for quality improvement at the source. Continuing the medical analogy, if a chronic condition is the consequence of a lifestyle, treatment will not produce a permanent cure.
It is also tempting to combine LQA and functional testing, because it is assumed that native speakers see more errors as they have a better understanding of the language, and because both tasks seem to blend well. But in reality, a native speaker who also has a thorough technical understanding for installing or configuring the software properly, checking all cases without missing anything, reporting bugs according to standards, etc. would be an extremely rare combination of talents. This is especially true if more than one computer is required or the setup is quite sophisticated. Goals and methods, as well as software, are quite different.
Finally, it may seem logical if a single vendor performs both translation & LQA. But there is a good chance that borderline LQA results would be �adjusted� (these results are often near or below the acceptable level in the lemon market case). Also, in some cases LQA results would be �covertly� taken into account during the correction stage, but not fully logged to avoid negative perception at the client end and to improve the overall picture. In other words, even if both services are separated at the administrative level, the issue of failed QAs tends to become political in large projects. And it often results in a significant share of errors either fixed �through the back door�, bypassing the QA, or simply left unlogged. Formally, everything is fixed, but it completely defeats the purpose, because both QA results and the initial quality assessment might be seriously skewed.

Building a comprehensive QA model

Let�s now outline an approach to measuring quality. As far as language quality is concerned, all of us have heard horror stories about unfair treatment, abhorrently skewed reviews, etc., and many of them are true! Therefore, I have divided all criteria that might be used for measuring quality into three categories:

Objective criteria are the ones that are universally recognized, univocal, and easily applicable. All violations/deviations can be clearly described and proof is universal, one doesn't need to know the language to understand marked errors. Typical examples include spelling and grammar, country standards, adherence to terminology and style guides, etc. Two people doing the same review based on objective criteria only will most probably come to the same results. Most objective criteria are applicable at a very low level, such as separate words or sentences.
Subjective criteria cover preferential, taste-based, obscure arguments like the following: �I don�t like it�, �This is bad�, �Poor style� �It sounds better that way�� In all such cases one can�t clearly explain what�s wrong and why, and the feedback is not well-structured.
Expert opinion-based (semi-objective) criteria is a third, semi-objective category, based on the fact that LQA is, regrettably, not all black and white. This category includes several important expert assessments, including overall intelligibility of the text, adequacy or equivalence of translation, language fluency, etc. Is it likely that if a trained expert finds the text incomprehensible or discovers serious deviations from the original meaning, so will most other readers? Certainly. Expert opinion-based criteria are mostly applicable to bigger chunks of text, such as paragraphs or pages, rather than words or sentences.

Based on this categorization, one can offer an approach to building a comprehensive, fair and objective LQA system.

Select the expert opinion-based criteria and define a grading system. Since these evaluations are not completely objective, each particular evaluation is NOT as accurate and bullet-proof as the one based on objective criteria. For this reason I would strongly discourage anyone from combining these two categories.
Let me provide a simple illustration: Intelligibility of the text as a whole (which falls under the expert-based category) is a major criterion by itself and overrides any other valuations. If the user can�t understand the text, everything else becomes irrelevant.
Since the evaluation according to these criteria is not objective, exact score rating might vary from expert to expert. I suggest rating it as pass/fail to eliminate incomprehensible or inadequate texts.
Select relevant objective criteria, clarify definitions and assign weights to different error categories to calculate an integral objective quality assessment. There are multiple models on the market, including the one developed by Logrus, and all of them use relatively similar criteria. The acceptance threshold may vary depending on the goals and expectations.
All subjective complaints related to style and other nuances should be consistently ignored.

Combine this recipe with representative sampling, and you get a more or less objective and robust quality model that is widely applicable.

Applying the model

First we generate a single, integral expert opinion-based criterion based on all expert-level (semi-objective) criteria, including intelligibility, fluency, adequacy etc. and set the �pass� threshold. If the text is not intelligible or adequate, it doesn�t make sense to delve deeper into details. Let me remind you that expert ratings are not completely objective, and there is a grain of subjectivity in each of them. We should be thinking about this subjectivity and natural variance of results when setting the threshold. So, for example, when I am setting the threshold to 7 out of 10, it actually means that I expect the average good result to be around 8.5, and allow another 1.5 points to cover the natural imperfections related to subjectivity. Secondly, we apply objective criteria to files that have passed the expert opinion barrier. These are already considered intelligible and adequate enough to talk about quality in more detail. As a result we get materials with two separate ratings: the integral expert rating, for example 7.8 out of 10, and the integral objective rating, for instance 8.6 out of 10. For the files that passed the expert opinion barrier we can combine these two ratings if we really want a single indicator representing quality. One thing to remember is assigning a relatively low weight to the expert rating to avoid excessive sensitivity to subjective nuances of that rating. Last but not least: This approach works perfectly with MT-generated materials. The only thing one needs to do is adjust thresholds, lowering them accordingly.

Assessing the overall quality of a document based on editorial comments

Wed, 01 Feb 2012 00:00:00 +0100

The problem

Is there a way to summarize pages and pages of editorial review comments into a single meaningful quality metric? Such a metric would enable technical writers who own multiple documents to decide how much time they should set aside to revise each document that comes back from editorial review. The metric would also enable managers of technical publications departments to assess the overall quality of all the technical writers� first drafts in the department. Technical writers and their managers can collect the metric over time and use it to identify trends in writing quality and, where required, take corrective measures to improve the writing. In addition, the metric, when collected over a period of time and analyzed, could reveal anomalies and patterns in editorial behavior, which can be used to tune and strengthen the editorial process. This article describes a process for objectively assessing the overall severity of editorial feedback for a document. The process can be used to distill hundreds of editorial review comments about a document into a single, quantitative metric indicating the overall quality of the document.

Why the usual methods do not work

First, let us examine how technical writers typically try to gauge the overall quality of a document based on editorial comments. There are three methods: Method 1: Count the total number of editorial comments. Method 2: Request an overall quality rating from the editor. Method 3: Judge the quality by reading the editorial comments. Method 1 (count the total number of editorial comments) is easy to implement, but it does not help us assess the true quality of a document. It overlooks differences in severity between individual review comments. Typos and grammatical errors, for example, are not as critical as missing and inconsistent content. It also ignores error intensity: the ratio of editorial comments to the size of the document in terms of word or page count. A 500-word draft that received 50 editorial comments is perhaps of a higher quality than a 250-word draft with 40 editorial comments. Table 1 illustrates the pitfalls of method 1. Table 1: Assessing the relative quality of documents based on the number of editorial comments - an example

Comment type	Number of comments in document 1 (100 pages)	Number of comments in document 2 (200 pages)
Typo	10	16
Violation of style guideline or grammatical error	5	5
Error in logic, missing content, or inconsistent content	6	2
Total number of comments	21	23

A simple count of the number of review comments would indicate that document 2 (with 23 comments) is probably of lower quality than document 1, but a closer look reveals that document 1 contains a higher number of critical errors, such as errors in logic and missing content. In addition, although document 2 received more editorial comments overall, the comments were spread across double the number of pages than document 1. So the absolute total number of editorial comments cannot be used in isolation to infer the relative quality of a document. Method 2 (request an overall quality rating from the editor) merely shifts the onus of assessing the overall quality of each document from the technical writer to the editor. Editors typically edit multiple documents pertaining to diverse projects and operate under tight schedules. It would be unfair to expect an editor to remember enough about each edited draft to be able to come up with an objective assessment of each document. Method 3 (judge the quality by reading the editorial comments) is subjective, difficult, and time consuming, and therefore impractical.

The proposed solution

We need a method that combines the ease of method 1 with the qualitative merits of methods 2 and 3. The ideal method should, at a minimum, fulfill the following requirements:

The method should yield an objective overall assessment of document quality based on editorial comments. Objectivity can be achieved only when the method takes into account the following parameters when assessing the quality of a document:
- The relative severity of each individual editorial comment.
- The error intensity: the number of errors per page or per 100 words. According to Donald S. Le Vie, this metric has a direct bearing on the quality (as measured internally, primarily) of a document.
The method should be reasonably easy to set up and use.

The severity of an individual editorial comment can be assessed based on the category of the underlying issue: typo, grammatical error, violation of a style guideline, error in logic, missing content, inconsistent content, and so on. As an editor marks up a draft, it should be a relatively simple task to annotate each comment to indicate its category. The annotation could be in the form of a special color or code for each category. After the comments have been suitably annotated with the appropriate categories, the annotations should somehow be amalgamated into a single rating�preferably numerical�that indicates the overall quality of the text. For this, each category must first be associated with a specific numerical weight based on the relative severity of the category. Note that this is a one-time effort. Table 2 shows a sample scheme of weights: Table 2: A sample set of weights assigned to comment categories

Comment category	Weight
Comment category	Weight
Spelling error	1
Grammatical error	2
Violation of a style guideline	3
Missing content	4
Inconsistent content	5
Error in logic	5
Wrong content	5

The sample weights that I have assigned in Table 2 are based on my personal judgment of the relative importance of various categories of editorial issues. I have provided them here merely to illustrate how the proposed method for calculating an overall quality rating works. According to this scheme, missing content is twice as severe as a grammatical error and four times as severe as a spelling error. Similarly, an error in content is five times as critical as a spelling error. The weights that I have assigned to the comment categories are admittedly arbitrary, but they are essential to convert the qualitative nature of each category description to a quantitative measure that indicates its relative significance. The next step would be to multiply the number of comments in each category with the corresponding weight, sum the resulting values, and calculate the error intensity (comments per page). Table 3 illustrates this calculation. Table 3: Calculating the relative weighted value of editorial comments�an example

Comment type	Weight	Document 1 (100 pages)		Document 2 (200 pages)
	Weight	Number of comments	Weighted number	Number of comments	Weighted number
	(A)	(B)	(A x B)	(C)	(A x C)
Spelling error	1	5	5	10	10
Grammatical error	2	3	6	4	8
Violation of a style guideline	3	2	6	3	9
Missing content	4	3	12	2	8
Inconsistent content	5	3	15	2	10
Error in logic	5	3	15	1	5
Wrong content	5	2	10	1	5
Total number of comments		21	69	23	55
Error intensity		69 / 100 = 0.69		55 / 200 = 0.28

As we can see from Table 3, although document 1 has fewer editorial comments (21 in total) than document 2 (23), the weighted number of comments for document 1 is significantly higher at 69, indicating that it received a relatively high number of comments that were severe in nature. In addition, in terms of error intensity, document 1 scores 0.69 errors per page while document 2 scores only 0.28. When choosing which document to take up first for post-edit revision, the technical writer can objectively select document 1 because it has the highest error-intensity number. The method proposed in this article will work only in an electronic review workflow that supports the following activities:

Technical writers submit documents for review electronically, preferably in a web-based environment.
Editors post context-specific comments, also electronically.
While posting comments, editors assign a severity level number to each editorial comment. Each severity level maps, internally, to a specific comment category.
The system calculates, dynamically, a weighted number of editorial comments based on the number of editorial comments at each severity level.

Some companies have already developed proprietary solutions that support steps 1, 2, and 3 of the above workflow. Oracle, for example, uses an internally developed web-based tool that allows technical writers to submit drafts for parallel review by multiple reviewers. The reviewers can post comments online, respond to comments by other reviewers, and assign a priority level to each comment. Converting the priority assignments to an overall rating at the document (step 4 in the above process) is the next logical step. Once that step is automated, technical writers who have to deal with and prioritize numerous editorial comments on multiple documents can quickly assess which specific pieces of text (sections, chapters, or documents) they should devote their attention to.

A few words of caution

Any metric such as those described in this article (�weighted number of review comments� and �error intensity�) is, at best, a numerical approximation of an abstract value. These metrics can never replace the original abstract values because the transformation process involves assumptions and, to a certain extent, personal bias. For example, while assigning weights to the comment categories�1 for typos, 5 for missing content, and so on (Table 2)�I injected my personal judgment that an error of missing content is five times as severe as a spelling error or a missing preposition. In some situations, a misspelling or an omitted word (the word �not,� for example) changes the meaning of the text completely. In addition, from a localization perspective, a spelling error might be more critical than missing content. Geoffrey Hart says that each company and context will have certain unique characteristics that change how you look at the review process. The work of setting up a process for assessing documentation quality based on editorial review comments does not end with defining comment categories, assigning weights, and designing an electronic workflow for capturing review comments and calculating results. The data generated by the process over a period of time across several documentation projects should be stored, and the stored data should be analyzed. For example, the data might show that one editor consistently posts a relatively high proportion of comments on style violations. Further analysis might reveal that this editor focuses the editorial review on only style-related issues and does not actively look for errors, such as inconsistent content. In this situation, something has to change: if the seemingly anomalous behavior of the editor is what the company expects as the standard, then the weight for style-related comments should be increased; if, on the other hand, the particular editor�s behavior is indeed an anomaly, the editor should be asked to alter his focus suitably.

Building a social network within an enterprise

Wed, 01 Feb 2012 00:00:00 +0100

Typically, social networks build on the following concepts:

Relationships
Influence
Identity
Privacy

An enterprise is a business organization characterized by the fact that it embodies the outcome of an individual or group who sets up, invests and runs a business to generate income and employment for itself and others. The difference between social networks in the enterprise as compared to the outside world, is the way in which the abovementioned concepts are utilized. For the sake of simplicity, let�s call the social network in the enterprise EnterWork�. Once you �enter� the enterprise, you enter �work� and the socializing that gets effective in EnterWork� is the one that helps you work better.

Relationships

Before we establish the EnterWork� platform that can be used for social networking in an enterprise, we need to understand the enterprise�s need to foster communication and relationship-building. It is a well-known fact that the success of an enterprise lies in its communication strategy. Communication patterns in an enterprise are either hierarchical (top-down), centralized (decision-maker at the center) or decentralized (everyone talks to everyone). Each communication pattern builds relationships in different ways. Successful relationship-building in an enterprise is about adapting communication patterns to the needs of individuals and the work assigned to them. Before setting up the EnterWork� platform several factors for effective communication need to be considered. For example, deciding whether there should be a discussion forum or an instant messenger for support depends on some key factors. The determining factors for successful relationship-building are based on:

The other person and their relationship / position in the enterprise
The nature of content being communicated
The criticality of a response or decision to be taken
The level of privacy required

Who then, in an enterprise, is best-suited to understand human behavior, interact with multiple and changing relationships, simplify technology, decipher communication patterns, design an appropriate communication strategy and foster relationships to ensure healthy business growth? This is where the technical communicator (TC) role can lead. The TC acts as a bridge between the content, its creator and its consumer. It is therefore imperative that the TC has a thorough understanding of human behavior as well as the content. Without the TC these vital connections will not form. The differentiating attributes of an effective TC are:

Fearlessness to face technology to either use or explain it
Ability to write precisely and concisely for the required EnterWork�
Ability to detect content patterns and aggregate them for appropriate audiences
Ability to design information
Patience in problem-solving/troubleshooting
Interviewing and listening skills
Usability and testing skills

The TC is best suited to generate, organize, publish and strategize content, and suggest an EnterWork� in an enterprise. EnterWork� is the platform used to foster the needs of an individual in the workplace and the needs of the enterprise to ensure maximum business benefits. In an enterprise, it�s significant to understand the type of relationships that are most important to encourage and design the EnterWork� tool accordingly.

Influence

EnterWork� is meant to encourage the free-flow of communication within an enterprise. This adaptive pattern is possible only when there is a well-thought out, researched and targeted communication strategy. When users within the enterprise want to take informed decisions, they face the problem that there is limited access to information. As a result users rely on other users to help take decisions. Certain enterprises have some advanced systems for data presentation and compilation. However, these tend to be discrete and scattered across domains and teams, again impacting the user experience. Since TCs are skilled content administrators and aggregators, they can distill and make available content effectively, thus influencing decision-making within the enterprise. This also enhances establishing any kind of communication pattern � hierarchical, centralized or decentralized. The EnterWork� should ideally show connections between individuals in an enterprise (up to three degrees) thus establishing identities, positions and connections. This in itself influences user�s behavior. Showing many opinions may result in few of them being influential.

Identity

In the enterprise, just as in the outside world, network users care a lot about how they appear to others. They think about how their communication or updates reflect about them. The most important thing to recognize and understand is that in an enterprise, users have multiple professional identities. Research has indicated that status updates on social media sites support important communication and social functions. Users have four primary reasons for updating their information:

to shape how others perceive them
to maintain and grow relationships
to share content that others might find valuable
to source information

One profile does not fit all the roles users play in an enterprise. They appear differently to different teams and to different domains, due to their extensive multi-tasking and multi-impacts. Because EnterWork� allows users to personalize how they appear to others, it helps build their professional identity. The TC�s inherent understanding of human behavior helps in designing profiles that appeal to individuals. His usability skills help operate the EnterWork� in such a way that users feel appropriately identified in the avatar they choose to work under, while still using the same EnterWork� identification.

Privacy

Privacy is a process of managing boundaries in the outside world. This is even more difficult in an enterprise considering intellectual property laws and enterprise-specific guidelines on sharing and privacy. While privacy in the social media context is about controlling how much other users know about you, in the enterprise, it turns out to be a problem of transparency - how much needs to be shared, even when all the required data is available within the enterprise. The EnterWork� needs to be absolutely transparent and it is critical that TCs accommodate for this invaluable user need. Users need to fathom the impact of their actions in the EnterWork� clearly. And as content designers, TCs need to do their best to make these things clear. Privacy and trust are two sides of the same coin. If users trust the EnterWork�, they�ll contribute to it, they will use it to be more effective with their tasks and they will feed it with reviews and data to make it even more powerful and trustworthy. TCs are best suited to understand behavior, not technology. And EnterWork� is more effective when its users start understanding that the EnterWork� designer cares about the communication that technology enables, and not just the bells and whistles technology brings. In conclusion, the technical communicator seems to have an edge over other domains in the enterprise in designing and implementing EnterWork�. Ensuring social network attributes like relationships, influence, identity and privacy are best suited for their enterprise, can be a TC�s core competency. And the direct goal of the TC should be to ensure that every professional�s answer to the question �What are you doing?� is �I�m EnterWorking�.

Psychological elements of customer acquisition

Wed, 01 Feb 2012 00:00:00 +0100

The word acquire originates from the latin ad quaerere, which means to gain/win/get/secure. The word expresses the thought that something must be performed or given to obtain the equivalent. Whoever is acquiring something must give or do something and obtains the equivalent in return. You should therefore persuade a customer to be able to secure something. I am not going to tell you how to acquire �correctly� or give you a guaranteed formula for success with this article. In fact I will go a step further and say and that whoever claims as such is a charlatan. Because: The success of acquisition pitches always depends on the situation and can be planned only to a certain extent � since you can actually influence only one of the two participating sides, namely your own. But even for the other, the customer side, there are possibilities of guiding the situation to some extent.

Your own situation

Let�s take a look at you first: When you conduct an acquisition discussion, it concerns a sales pitch. You want to sell yourself and the services you offer. And whoever would like to sell, should be in a corresponding good mood. How do you do that? Very simple, since it happens by itself, but more on that later. Your first thought should be to create a positive resonance with the potential new customer. Because, irrespective of how well you prepare for a talk, your customer, as the recipient of your messages gives the meaning to your words � and not you. It is therefore important to generate goodwill at the beginning of a sales pitch. Or, if the situation does not allow that, to cancel the discussion and move it to a later date. Right now you are probably thinking: �Cancel a discussion� � the author probably has no idea of how it is for me. Of course I do! And believe me: Many times it is better to state the situation. When a problem is addressed, it loses its pressure, making the (new) customer feel as if he is understood and will be happy to start during a subsequent discussion. Tip to articulate what you say: �I can see that you have a lot going on right now. When would be a better time tomorrow to contact you? Preferably in the morning or afternoon? �

The way to emotion

The molecular level of this goodwill is the hormone oxytocin � also known as the � relationship hormone�. It ensures that a trusting situation is developed between two conversing partners. If you manage to be the person that stimulates the oxytocin production of your conversation partner through contact, then you �land� in his emotional memory as a memory � and that�s right where you want to be! This almost answers the question of what is the most prudent way to acquire customers, since resonance can best occur during personal contact. Even though communication is almost always through electronic media today, you should try to make an appointment for a telephone call. If your contact resides locally in the region, it is worthwhile to invest the fuel money for a face to face discussion. Tip to articulate what you say: �To avoid a �mail campaign� and any misunderstanding I would like to make an appointment to talk to you personally on the telephone. Would it be alright if I called you on ...?� Your customer doesn�t decide rationally, but always emotionally. Even if he is the most rational �type� that you know � move away from any kind of categorizing. He cannot do anything other than decide with feeling. Because, before we can consciously discern something, our brain has already filtered out a maximum of 100 bit/s from up to 50 million bit/s and made it available to us � this is what we actually perceive. The emotional assessment of a situation has a time advantage of a just about half a second! You should therefore try to reach your counterpart emotionally. The rest comes later, such as prices or delivery periods. Theoretically simple rules apply here, such as �Birds of a feather flock together�. Why are many business transactions made at the golf or tennis clubs? Both types of sport lead to not just swings from the player, but also provide fresh air, sportive competition and joint experiences with the involved partners. The golf course can therefore be said to be utopia in the context of acquisitions.

On the other side of the golf course

Now, except in beautiful Utopia, you cannot spend your professional life having discussions on the tennis court or the golf course. You need not do so as well, because you can carry a piece of the golf course with you virtually, by trying to build on similarities with your counterpart � called pacing. This is not about aping your counterpart or telling him what they want to hear, but about working out small commonalities. This includes body language or the speed of speech. Your first attempts should however be started within the family or friend circle, since pacing requires practice. Take the time for a longer bonding phase and don�t attack your customer. As before, we can learn from the Arabian and particularly from the Asian region here. There it is common to get to know each other personally first before moving over to negotiations. Once you build trust and are able to increase the oxytocin level of your counterpart, the rest becomes that much easier.

Effective sales arguments

What is the best time in a discussion to trigger the main argument for the sale? Two psychological effects face each other here: the primary and the recency effect. According to the primary effect, things said earlier are retained better than those stated later. This initial information �competes� with lesser other information than the information provided later and therefore reaches long term memory more easily. The recency effect is the opposite. It shows that information flowing in later has a greater impact than that received earlier. This applies mainly when this information is easier to recall � that is contains exciting information as compared to the earlier information. In marketing and sales the recency effect has found its way in the form of the technique of reserve arguments: This technique states that the strongest argument should be saved for the end of an acquisition or sales discussion.

When is it time for the discussion

As already said, it is important to be in a good mood, when you attempt an acquisition. You don�t need any psychological tricks for that. Use situations that lead to your feeling good � in which your dopamine level increases and gets you in a flow. This is always the case when you have just received good customer feedback for instance. Use this mood, pick up the telephone and dial the number of the person from whom you want to get an order.

Don�t forget existing customers

Acquisition doesn�t just mean winning new customers! Also think about your existing customers and win them over. After order processing ask your customers specifically about their satisfaction. Criticism helps you to improve in the future. And when your customer is satisfied with you, request for a recommendation with colleagues or professional associations. You can guide your flow by yourself to some extent in this way. Are you anxious about an upcoming sales discussion? Then briefly call a customer from whom you are sure to get positive feedback. Then pick up the receiver and dial the number of the customer from whom you have been hiding for long. Moreover: No one can help you where one thing is concerned. When you want customers, you must speak with them. Even when you think you are an introvert and shy: You have given up on any kind of typecasting for your customers after reading this text. Do the same for yourself. You are not shy and introverted, but you just behave so in certain situations. It therefore makes sense to analyze your own strengths and weaknesses, which have come to the fore in the past. What may have lead to past sales discussion failing? Often, it can even be helpful to get external feedback to check how you conduct the discussion. Then go to your next discussion with this knowledge, and pay attention to resolving your errors and developing your strengths.

Collect arguments, define targets

A good acquisition discussion demands preparation. Create a checklist that you can use for all coming discussions. This is a onetime effort and greatly facilitates coming discussions. Defining your targets is the first step of preparation. What do you want to achieve specifically through this discussion ? Don�t create lofty targets, otherwise you are preprogramming disappointment. The target of an initial discussion can certainly be �being admitted� to see the correct person, introducing oneself and agreeing on a follow up discussion. The order is not always the target! Therefore, define a realistic, an optimistic and a pullback target for yourself. The realistic target is what you assume you will achieve. When everything runs optimally, you achieve more than you have predicted and then you have reached your optimistic target. Apart from that always have a pullback target. This means an alternative to the attempted target. If you identify during a discussion, that your contact will definitely not give you any business, then it can be a pullback target to find out whether and when you may contact him again. Or whether your discussion partner has colleagues who could be interested in your services.

Identifying your conversation partner

A further step towards good preparation is collecting information. Who is the responsible person to the contact in the offices of your potential customer? Thanks to the Internet and social media you can already find out valuable information about your conversation partner before your discussion. You can build your discussion strategy based on this information. It is worthwhile creating a list of specific questions for this. These questions should be a series of open questions, which are usually identified by their initial alphabet:

How is technical communication run in your offices?
With which partners have you collaborated so far?
What is especially important to you?

The objective of an acquisition discussion is to allow your counterpart to speak for the greater length of time, and speaking less yourself. Because your goal is to find out the need of your potential new customer to then formulate a fitting offer. Naturally, you must carry all facts in your head when your conversation partner asks you something specific. Therefore preparing for acquisition also includes compiling all relevant figures, data and facts. The list of questions is a valuable aid not just during telephone conversations. Don�t hesitate to prepare a list of questions even for personal discussions. In this way you are able to check whether you could collect all the information, which you felt was important before the discussion.

Self-praise is no praise?

No! Don�t shy away from mentioning the advantages of your company openly, as soon as you have asked about the needs of your discussion partner - the kind of similar projects that you have already worked on successfully, the customers you have worked with and why it went well especially because it was you. You want to sell yourself and this includes the �properties of your product� � this has nothing to do with self-praise primarily. It is much more about working out the positive aspects that cover the needs of your customer. Therefore, observe the needs of your customer and identify what moves and drives him. Your arguments should be in line with this information.

Summary

There is no guarantee for success. Therefore keep your chin up if you don�t reach any of your targets sometimes � in spite of preparation and everything that goes with it. Your potential customer gives meaning to your offer. And perhaps you simply called at the wrong moment, at the worst possible time. Doesn�t matter, because the quality of your sales attempts will improve with good preparation and some practice and you will have more success in the medium term. What are you reading here? One of my sales tools. Therefore: Also consider how you can present your services to your target audience and strike out on new paths. The worst your counterpart can do is say �No�!

Illustrations based on 3D CAD data

Wed, 01 Feb 2012 00:00:00 +0100

Both ways are based on CAD data from design. However the way the data is processed further differs significantly depending on the budget and required quality of the target files. The paths have already been tested in practice in projects: Version A for high value device documentation of a medical device, the more cost effect version B for plant documentation.

Version A � 3D illustration

CAD data must be available in an exchange format such as STEP or IGES for this version. This raw data was processed by an experienced 3D technology graphics expert in several steps for the practical project for a medical device. The end result were photo realistic images in TIF format, which were used in the manual. The graphics expert could rotate all or individual objects as required, define the surfaces and control the brightness and contrast settings. Depending on the effort that can be invested, it is possible to achieve a quality of images that cannot be differentiated from photographs by most users. Unlike a photograph, the product does not need to be available in its final version when the image is created, which is definitely an argument in favor of the illustration during short development cycles. There were two more reasons to go the way of 3D illustration in our project:

Existing manuals had primarily been illustrated with isometric or 2D line drawings. These require a small step of �translation� towards the real device by the users� minds. Users without technical knowledge accept line drawings only to a certain extent.
Since animation films were already planned for marketing purposes using the 3D data, the prepared data could be used jointly.

Image 1: Example for an isometric representation for how it was used for preceding products (Version A).

Version A - Process and tips

The raw data in STEP format is converted in the first step and cleaned of superfluous objects in 3D software. If components, parts from vendors for instance, exist as separate STEP files, they must be added to the entire group. Missing parts, such as outsourced items must be reconstructed in 3D. Once the base data is complete each object is assigned surface properties in 3D software, e.g. Maxon Cinema4D or Autodesk 3ds Max. The type of light source and the positions of the lights are then defined. Individual areas need to be illuminated with additional sources of light in some images, so that these areas do not appear dark, because they are in the shadow of the defined standard sources of light. The files are subsequently rendered as so called previews with a resolution of 300 dpi. The program Mental Ray is appropriate for this process, for example. The graphics expert delivers the previews to the technical editors for a check. Once the previews are approved, the images are finalized. This means, the graphics expert improves the brightness and contrast, adds shadows, evens out colors and cleans up where necessary. Image 2: New 3D illustration of the same component (Version A)

Version A - Recommendations

The following is recommended for using 3D illustrations in technical documentation:

Specify with the graphics expert before the beginning of the project: How much photo-realism is necessary? Which colors should be used and how? What dimensions should the images have? How are movements shown? How are objects highlighted?
Submit the first sample images to a larger committee for approval, before many illustrations are created in the selected style.
Provide the most definite specifications possible for the illustrations required: Text alone is hardly suitable for conveying information about images. Better: Provided photographs of a device prototype or images of earlier products with comments. PDF is suitable for this task. Even better: a video conference to see the images together on the monitor with external graphics experts.
Check the first previews thoroughly to ensure that all objects relevant to operation are available in the base data, e.g. the small lever found below a flap and required only for a specific maintenance task. This saves subsequent work on base data with possible impact on the previews that have already been completed.
Mark the TIF-files with XMP-metadata to be able to differentiate final files reliably from previews. We have consciously selected identical file names in the practical attempt, to allow exchanging referenced previews with their final version without any problems in Adobe FrameMaker.

Image 3: Representation of steps in 3D illustration (Version A)

Version B - 3D screenshots

Our second version is based on screenshots prepared with the help of a 3D-Viewer. It is therefore much simpler, since the technical editor can prepare the screenshots himself, and the collaboration with an external graphics expert is not required. The results cannot be compared with professional illustrations, but then that is not the objective at all. The images and details are intended for experts, in our case for the operations and maintenance personnel. The important advantages of this method lie in the quick and economical realization. Compared to photographs, it has the additional plus point of being able to clearly map large objects such as a hall sized plant. Image 4: Example for a 3D mapping based on screenshots (Version B) The plant manufacturer provides the CAD-data in an internal exchange format DXF in AutoCAD, but all other proprietary CAD formats are also possible. The only prerequisite is that a license-free view is available for the format as far as possible. The viewer should also allow rotating, moving and hiding selected objects or even making them transparent. Moreover the viewer must be able to save views. In our case, we use the program AutoDesk Design Review.

Version B - Process and tips 

Even though this method appears trivial, a design process saves time as well in this case. Before the technical editor begins creating many screenshots from different perspectives, he should think about which perspectives are appropriate for most of the required images. He should save base perspectives as views in Viewer to show several images from the same angle. It is obvious that the editor should select a very natural perspective corresponding to the visual angle of the user. It is also advisable to save the views from which screenshots were created. In case changes are made later, there is a defined starting point.

Version B - Recommendations

The compact but loss free format PNG is recommended for saving the screenshots. The PNG screenshots are imported to Adobe Illustrator, to apply position lines there and to reduce them to previously defined image size. In spite of the shot with just 96 dpi, a resolution of 200 dpi for an image width of up to 13 cm can be realized by scaling (without recalculation) which is sufficient for laser printing. Even objects missing from the CAD data or roughly modeled objects of outsourced parts can be added in Illustrator, e.g. switch, keys or control displays. However, this perspective post processing is time-consuming and naturally has to be completed again for every changes perspective. The completed Illustrator-files can be referenced directly as EPS in layout program, in principle. Since we were using Microsoft Word for the plant we were documenting, we decided to save the files in PNG format due to the greatly reduced file size, and to insert and link them in Word. Performance of Word does not have problems with the typical file size of between 100 to 300 KB for the 3D-images. The instructions illustrated in this manner have a volume of about 150 pages.

Summary

3D illustrations convey a photo realistic impression and are found to be more expressive by many as compared to line drawings. The type of representation is optimally suited for product representations. To some extent it is difficult to position movement arrows clearly at a component part to show maintenance tasks. For future projects we are considering reducing the degree of photo realism in favor of better options for highlighting. The limits of this method are reached when it concerns showing the same tasks for different component parts, e.g. cleaning. Like photographs, the images are so concrete that a separate image is usually required for each component part. The image quality of 3D screenshots is not comparable in any way. However the plant operator found the technical documentation with the screenshots to be so positive overall, that it can be considered for other suppliers as reference document. For similar costs, the only alternative would have been creating few drawings, i.e. 2D overviews and representing details and work steps with separate photographs. The 3D screenshots are a better alternative in comparison, especially when during completion of the documentation a part of the plant had already been assembled and could be photographed.

Links to version A

http://de.wikipedia.org/wiki/Standard_for_the_exchange_of_product_model_data
http://en.wikipedia.org/wiki/ISO_10303

Links to version B

http://usa.autodesk.com/adsk/servlet/index?siteID=123112&id=7454811
http://de.wikipedia.org/wiki/Portable_Network_Graphics

Creating a good impression with the title page

Sun, 01 Jan 2012 00:00:00 +0100

Typographic design has special significance for that part of a technical document which is seen first: the title page of the cover. The goal is to make it as advantageous as possible. The first prerequisite for this is that only those components are shown on the title page that actually belong there. According to the formula "What and Who", the title page is an object that is described inside the manual, and consists of an image with captions for the purpose and the name of the product, as well as the identification of the manufacturing company through a logo or emblem. Do not use any other data while designing the title page. Organizational or legal data may as well be placed on the second cover page. But do not leave out color. Some sample pages have been shown in the below sections. Some of these are actual title pages of manuals, but with the names removed. The examples are intended to show design options from the perspective of typography and based on the DIN A5 format.

The botched title page

Figure 1 shows a title page as it should not be. The idea has been implemented well to some extent. A beam-like shaded area at the top and on the side, complemented by a shaded area for the image has a high recall value. This can play an important role when these elements are defined as a design requirement for a product series. Fig. 1: A not very good example of a title page. Image: Manfred Siemoneit However, the product has not been represented properly. The insignificant image has no relation to the product value. To represent such an expensive item in such a simple way provides no advertising for the manufacturer. Using the word "Washing machine" (�Waschmaschine�) to identify the object uniquely is downright outrageous. Apart from that: Why should the object be represented so small, when the area, which is intended for the image, would allow a much larger representation? Anything that looks small and tiny is also perceived as such. Similarly, the notes are also placed incorrectly. Where they would look better is explained at the end of this article.

An alternative

The representation in Figure 2 is much better. The basic idea behind the design is retained, as lines, shades and colors are the three design options with which text and images can be represented. Fig. 2: The basic idea is retained, but overall, the page has been extensively modified. Image: Manfred Siemoneit

When designing a title page, it is advisable to use a colored product photograph. Whether the product is photographed only from the front or as in our example, is ultimately decided by the representation in other media, such as the Internet or in sales literature. A consistent representation is decisive in achieving a high recall value. A color other than grey brings conciseness to the design. Also, washing machines are usually painted in light colors and the product is clearly emphasized by a dark background. What has also changed is: The shades have an optically visible relationship with each other. From a typographic point of view, this makes it easy on the eyes. The word "Instruction manual" (�Gebrauchsanleitung�) was written in a tilted fashion and with the foot to the outside. This suggests to the reader that it continues on the next page. Tilted lines are always an interesting variant to display captions. Instead of using the inconspicuous "de" as the country code, the title page had the internationally accepted form of the country code.

Interesting design - without text

Figure 3 has no text at all. Instead of the words "Instruction manual" or "Manual", a pictogram that supposedly indicates commencement was used. The colored shades are suitable for images. From a typographical point of view, the following should be considered while using them: Never use the ratio of 1:1 for a two-tier area - that's boring. 2:5, 3:5 or 3:8 as shown here, make the design interesting to look at. Fig. 3: Title page with no text. Image: Manfred Siemoneit An image doesn�t always need to be exactly in the middle. Images that are cut beyond the format or motifs that are reproduced in part, like on this title page, make for an interesting design. However, it should be noted that even if the motif is reproduced only partly, it should still be recognizable. To select the language, the title page has country codes. If the title page is used as an interactive PDF, the technical editor can link the corresponding language version to the country code.

Not always formal

It is quite possible to design a title page with humor, as shown in Figure 4 (Translation: �This doesn�t need to be� �when using your vacuum cleaner correctly�) One thing is for sure in this design: It is memorable because it is designed differently. But for the technical editor, this would mean a cutback and moving away from conventional forms. The following should also be borne in mind while making a humorous design: The inner contents must follow this direction, without calling seriousness into question. This might be a devious idea for some editors, but it can be quite effective in advertising and meets the taste of the users. Fig. 4: Humorously designed title page with an alternative text suggestion. Image: Manfred Siemoneit Speaking of advertising, if a company decides on this form, then it must be done consistently. Thus, creativity does not begin with the technical documentation, but right with the initial activities of offering a product. The picture shows the format divided into three shades. What is clearly evident is, color shades are always a good recommendation for design, because they are striking and concise.

And without the title picture

For some products such as software, it is difficult to use pictures. Figure 5 shows an example of how to illustrate the title lines thematically: The topic of "Diagnostic system for doctors" is represented by a stethoscope. Many software products can be represented by characteristic symbols. Image databases in the Internet can provide ideas. Fig. 5: Title page with creatively integrated back page. Image: Manfred Siemoneit It is important to note here that if the technical editor designs the front page with a colored shade, then the outside back cover must also be similarly designed. It seems abrupt to the reader if the color ends at the fold. By continuing the colored area, the editor can establish a connection to the data that is on the outside back cover. It is advisable to edit the following facts: company address, service address, probably reference to other products, and in-house organizational data.

The title page in landscape format

So far, only the portrait format has been discussed. However, a landscape format can also be used depending on the subject. Figure 6 shows this format very well in sync with the image motif: as a colored image with an integrated, realistically depicted motif. Fig. 6: Elaborately designed title page in landscape format. Image: MAN Truck & Bus AG, Service Documentation SAWD A landscape format offers other benefits over the portrait format, especially in the inner part. While only two columns can be placed side by side in the portrait format DIN A5, three columns are allowed in the landscape format. This has the advantage that shorter descriptions can be set in the columns without wasting too much space. The rubricated character can thus be clearly underlined, which makes reading easier. Apart from this, three-column design is always more interesting than one or two columns, from a typographical point of view. In terms of the layout work, both formats are equal.

Behind the title page

The second cover page is suited for legal information. This page should not be overlooked, as printed documents are normally read from the cover page. The same applies for PDF documents. Branches should therefore begin at the earliest in the table of contents that precedes the text. In case of branches in foreign languages, it must be ensured that the text of the second cover page is shown first. The alternative is: All languages are placed on the second cover page. Copyright notices, safety tips or tips for using the manual are the most striking parts of the second cover page.

Conclusion

Technical documentation mostly follows formal requirements; there is barely any place for creativity. The title page is an exception which can impress customers with its inventive design. The aim is to attract the customer even as he holds the manual in his hand for the first time. Finally, every technical editor must realize that an attractive title page cannot outweigh the typographical weaknesses of the inner contents.

Setting up a comment feature for online Help

Sun, 01 Jan 2012 00:00:00 +0100

Not everything that is technically possible makes sense conceptually. Therefore, the question of whether and where a comment feature is useful at all and where it may even prove detrimental, is raised at the very beginning. A full treatment of this question would fill an entire post, so only a brief summary of the advantages and disadvantages of a comment feature is given at this point.

Advantages:

Users feel involved in the development of the product. This encourages customer loyalty.
Manufacturers get real-world feedback about weak points in the product and documentation.
The technical editor gains insight into actual usage scenarios.

Disadvantages:

The contributed information may be incorrect, incomplete or �politically undesirable�.
The contributed information may be difficult to understand.
If an evaluation feature is incorporated and the evaluations are negative, then the credibility of the associated document decreases.

Hence, it must be well thought out whether a comment feature should be integrated or not. Perhaps, only certain parts of the documentation or only certain topics are suitable for it. In any case, a fairly large number of users who are ready to contribute actively to the contents are required. This is rarely more than one percent of all users. Hence, the technical editing team itself should be active in the beginning and initiate discussions. In addition, a person belonging to the company should be responsible for checking the content and act as the moderator.

The basic components

All solutions consist of the so-called frontend and backend. The frontend includes the comments and evaluations in the Help topic and displays a form for entering the comments - Figure 1. Fig. 1: Front end for the user, implemented here with www.cubescripts.com. The backend is a web-based user interface that enables you as administrator to confirm, delete and edit the comments and evaluations � Figure 2.  Fig. 2: Back end for administrators, using the example of www.cubescripts.com. Individual settings and format requirements are set either using configuration files and style sheets or even through the backend. Comments and evaluations work only with an uncompiled Help that can be displayed directly in the Internet browser. Also, the online Help must be on a web server, as PHP code needs to be executed for the integration. If you want to address a comment function from a CHM file, this is possible only in an indirect way, such as via a pop-up or iFrame. Some hosted solutions, however, work with JavaScript also as we will show later.

Solutions in authoring tools

Only a few Help authoring tools offer a built-in feature that allows you to integrate comments and evaluation features at the press of a button. Some of these features are also very expensive. An overview:

In Adobe AIR Help with "Adobe AIR Comments", RoboHelp offers a built-in functionality for comments, but only in Adobe AIR format and not for any other browser-based Help.
For Flare, there is a complementary product "MadCap Feedback", which costs about $1,800.
A complementary product is available for HelpStudio and Document! X also. The "Community Extensions" package costs around �1,100.
Help & Manual offers a simple connection to the Internet services "IntenseDebate" and "Disqus" in the optimal premium pack that costs �80.

Solutions by providers

If your authoring tool does not provide any feature to integrate comment and evaluation features, the simplest solution is to use an external provider. In some cases, such "hosted services" are even free. What are the pros and cons?

Advantages:

no separate SQL database required and no separate server with PHP support required
mostly JavaScript-based, without PHP on one�s own page
minimum configuration effort

Disadvantages:

dependence on the availability of the respective service
data is not on your own server
rather unprofessional appearance, if the user notices that an external service is used

Steps for integration: When you register, you receive an ID from the provider. You enter the ID in one or two ready-made JavaScripts. Then you add the JavaScript in place of your topic template, where the comments and the links to the comments should appear. Now when you generate the Help, the comment feature is already integrated. You can manage the comments via the online access of the provider. Providers - the best known services that are free of cost at least in the basic version:

DISQUS
IntenseDebate

Commercial script solutions

Most of the commercial solutions are PHP scripts with a more or less comfortable backend. The installation, integration and usage do not differ significantly from the open source systems described in the next section. For example, configuration is much easier with the XcommentPro software, which costs about $100. Here, you can set important settings and formats through a graphical user interface and do not have to manually intervene in the style sheets. Providers - the following web sites provide a good overview of commercial scripts:

www.hotscripts.com/categoryphp/scripts-programs/reviews-ratings/
http://codecanyon.net/searches?term=comment&type=files

Free script solutions

Although there are only a few open source programs to incorporate comments and evaluations, they are at par with the commercial products. Examples of open source scripts are:

www.commentics.org
http://ratherodd.com/commentator/

In the following sections, we will show you the installation and integration using the example of the script solution Commentics 1.5. Setting up Commentics is not a difficult task even if you have no experience in installing on a web server. Help & Manual is used for our online Help example. However, the principle is the same for all authoring tools. The only requirement is: The templates underlying the Help pages must be editable in HTML. At least you should be able to insert HTML snippets there. This condition is fulfilled by all professional Help authoring tools today, sometimes even by some of the tools under 100 �. For the installation, you need a web server with PHP and SQL as well as FTP access to this server:

If your company operates its own web server, you need to contact your system administrator.
If your company uses the services of a provider, you need access to the administration area of your internet package. With almost all providers, you can make the necessary functions and settings easily via a web-based user interface.

To test the script solution, you can also install a web server locally. For Microsoft Windows, free packages are available, including installation programs:

XAMPP
MoWeS Portable
WampServer

Apple Macintosh users can use Mamp. Step 1 Create database: In the first step, you need to create a SQL database on your server. This is usually a button on the administration interface of your Internet provider. Note the database name, user name, password and host name. Step 2 Download, unzip and customize the script: Download the comment script that you want to use from the Internet. Unzip it to a directory on your local hard disk. In one of the script files, you must now enter the previously noted details of your database, in Commentics, this is the file "connect.php" - Figure 3. Fig. 3: Enter details of your database. Step 3 Upload script and set access rights: Now upload the entire script via FTP to your web server. Be sure to set the permissions for the files as described in the documentation of the script. It is easy to adjust the rights using an FTP program like FileZilla: Just click on the file with the right mouse button and set the required permission. In Commentics, you must set the permissions for the file connect.php as 444 - Figure 4 Fig. 4: Adjust access rights using an FTP program � here FileZilla. Step 4 Execute installation script: Finally, open the installation script that requests additional information step by step from you, for example, the user name and password for the backend - Figure 5. Fig. 5: The installation script of Commentics. Finally, the installation script creates all the required fields in the database. Step 5 Integration into the production process of the online Help: To integrate into your online Help, add the three snippets of HTML and PHP code that have been provided, to your topic template - Figure 6. Fig. 6: Code snippets inserted into the topic template. Important in Commentics: There should be no blank line and no spaces before the first snippet. While generating your Help, you must make sure that the topics are not created as *.htm or *.html files, but as *.php files. Most authoring tools have the appropriate defaults in the export settings. In some PHP installations, �UTF-8 byte order mark" may result in errors if it is set. Therefore it should not be set - Figure 7. Fig. 7: Export settings in the Help authoring tool - here Help & Manual. If your authoring system does not offer any PHP output, you can rename the HTML files themselves. It is best to use a suitable tool for searching and replacing, because you need to change not only the file name, but also all links and other references within the files. The following tools may be used for this:

PowerGREP, about � 119
Text Workbench, about $ 50
AKS Text Replacer, about $ 40
FART, Open Source
Swiss File Knife, Open Source
Rainbow, Open Source

If you upgrade your Help more frequently, then you should make sure that the search and replace starts at the command line level. Alternatively, you can also configure a web server such that the PHP code is also executed in HTML files. This eliminates the searching, replacing and renaming of files. Step 6 Copy the online Help to the server: Since your online Help is now in the PHP format, it can only be accessed on a server with PHP support. Copy all the data belonging to the Help via FTP to your web server. Now when you call the Help, a comment field is available in each topic - Figure 8. Fig. 8: Topic with comments, converted with Commentics without changing the style sheets provided. You can manage all the comments from the backend as administrator. You can also set which fields are displayed to the users while entering comments via the user interface - Figure 9. Fig. 9: Managing the comments in the backend - here Commentics. Step 7 Customise design: If everything works as intended, you should finally adjust the design of the comments to the design of your online Help. This can be done by editing the linked CSS file.

Expanding search

Almost all of the proposed solutions have a disadvantage: The text of the comments is not indexed by the full-text search of the online Help. Currently, only RoboHelp has the feature of including external sources in the search. If you want to include comments in the search index in other solutions, you must replace the default search through a custom search routine. Solutions that can be integrated with a few lines of code are available for this also. However, in most cases, one can live with the restriction on the scope of search. There are even reasons to exclude comments from search, so as to take the user directly to the given content and view comments only as an addition.

Conclusion

To provide a comment and evaluation feature in an online Help, your authoring tool need not support the integration of such a feature explicitly. The easiest alternative is to use the service of a specialized provider for the comments and evaluations. Apart from including a small ready-made JavaScript snippet, you need not change anything else in your online Help. If both the online Help as well as the database for the comments lie on your own server, then there are ready-made commercial and freely available PHP scripts for this. Installing a script on your server and including it in your online Help can be accomplished even without in-depth programming and IT skills. But whether integrating a comment and evaluation feature in an online Help is always useful is another question altogether. Even if such features are now found in more and more places, they are useful only if a sufficiently large number of users contribute content and a moderator reviews the comments and evaluations continuously.

India offers new business opportunities

Sun, 01 Jan 2012 00:00:00 +0100

In an economy that opened its doors to the world a little over two decades ago, this demand is being met, even today, not only by Indian companies but also by companies from every conceivable corner on the face of this earth. And while reaching out to the Japanese in Japanese and the Chinese in Chinese forms part of every communication strategy in every boardroom worth its salt, the thought of reaching out to Indians in Indian languages only crosses that rare business mind. Perhaps there are far too many Indian languages for anybody to care. But consider this: not very long ago, the largest number of the Mercedes-Benz cars in the state of Maharashtra were sold neither in Mumbai, which is the financial capital of India, nor in Pune, a vibrant city known for its bustling industrial activity. They were sold in the little-known town of Aurangabad, where the predominant language is Marathi. A group of people from Aurangabad bought, not one, not two, but a whopping 180 Mercedes-Benz cars in one go. Similarly, even the close to 100 million mobile phones that Indians buy every year are bought not always by those who speak English but increasingly by those who speak one of the many other prevalent Indian languages. Close to 72% of India�s population lives in rural areas, not exactly the best of places to find people with the most impeccable of English language skills. Statistics show that the number of English speakers in India stands at only a little over 11%, and although India ranks fourth in the world with 81 million internet users, that number is barely 7% of India�s total population. The remaining 93% of the people are unable to use the internet not because it has not reached them, but because for the most part it is not accessible to them in their language. Reality actually suggests that the business world is speaking to India in a language that it does not quite understand or use by choice. Let us say that one Mr. Satish Kumar, a Hindi-speaking gentleman from the interiors of Uttar Pradesh, wants to buy a car. He starts scanning through newspaper advertisements and the many offerings that dot the landscape of any Indian city, in the hope of acquiring more information about cars and the current deals offered. To his not-so-utter surprise, they are all in a mixture of Hindi and English, better known in India today as Hinglish. He then decides to check out the internet, only to find that not only are the websites of most companies available only in English, but even websites that review products (cars, in this case) are also mostly monolingual (read: English). He chooses to ignore this linguistic marginalization and goes ahead and buys a car. He is pleased and excited about his new purchase and decides to spend some time that evening reading the manual of his car so that he can get to know it a little better. But alas! Even the user manual is in English, a language that he barely manages to understand. There are millions of Mr. Kumars out there buying a great number of products, and their linguistic plight only points to a dichotomy. While manufacturers the world over want a share of the Indian pie, not all of them are making an effort to reach out to Indian consumers in their languages. Most attempts at using Indian languages are mostly limited to advertising. However, from automobiles, electronics and medicines to food, shelter and clothing, the average Indian is buying something. Billions of rupees are being spent on the best of products, but product documentation is not always available in regional languages. No offense meant, none taken. We Indians get what we seek. If the globe-trotting, English-speaking Indian gives the impression that India speaks English, the business world can be forgiven for its folly. What is at best a colonial hangover is precariously deceptive in its very essence. And though the well-educated English-speaking socialites of every New Delhi and Mumbaiesque city might come across as representative samples of markets that global majors would like to tap, cities do not make India. Villages and smaller towns do, and so do the millions who throng to cities to earn their livelihood, only to repatriate most of their money back home. The real consumer is therefore the ordinary Indian whose buying power is increasing with every passing day and who is not necessarily well educated and certainly not always at ease with English. Indian consumers are waiting to be pampered and addressed in their own language. So what does that mean to language service providers (LSPs)? Well, to begin with, it means newer ways to tap business opportunities. Of course, this is not ready business. Your existing and potential customers who might have an eye on the Indian market are not even aware they need to speak to Indians in Indian languages and perhaps the Indian consumer doesn�t believe in any such luck either. But that is where the opportunity actually lies. There is a popular anecdote that makes the rounds in Indian management schools. A CEO of a popular footwear company, it seems, sent his sales head to a certain country in Africa to see if there was any potential for this footwear in that part of the world. After some extensive traveling and discussions with various people, the sales head submitted his report that said there didn�t seem to be too much of a demand because not many people in that country wore footwear in the first place. Putting the report down, the CEO said, �Well, it looks like a great market to me! All you need to do is educate people about the benefits of using footwear and then introduce our brand.� In under a year, the company�s revenue shot up by a good 200% with this African country making the single largest contribution. Even if this is, perhaps, only an anecdote, if used as an analogy, there are some thought-provoking lessons to be learned. At a time when LSPs are struggling to remain competitive, retain customers and offer greater value, this could open up a potentially untapped market of over 1.2 billion people. The over two dozen official languages that the people speak can be used as an effective tool to make significant inroads in the public psyche. Today, it is rare to find a country that has nothing to do with India. Businesses in your country are either buying from India or selling in India. LSPs only need to first identify and then initiate a dialogue with such customers. A novel sales pitch has to be devised to drive home the importance of making documentation available in Indian languages when selling in India. Thanks to technological advancements, even Indian scripts are compatible with the various software and technologies that LSPs use, just like any other language. And then again, it is rare to find a country where Indians have not settled. The good news is that LSPs do not need to start from scratch. The winds of change have begun to blow. Slowly but steadily, businesses are waking up to the idea of speaking to Indian consumers in Indian languages. Even if they form a small majority, their number can be compared to practically only a handful a few years ago. A world-renowned tractor manufacturer from the private sector chose to translate all its online training modules and sales literature into all major Indian languages. Farmers and dealers in villages being their target market, they thought it would help them sell more. And it did! Even the public sector is not lagging far behind. The MCX Commodity Index is now available in 11 Indian languages, thereby making it possible for more Indians to use it. However, this is only one side of the proverbial coin because we are still talking about LSPs finding potential customers in only those who are looking at entering the Indian market. But what about Indian companies that are looking to go global? According to the SME Chamber of India, there are a staggering 30 million small and medium-sized enterprises (SMEs) in India operating in the manufacturing as well as the service sectors with potentially another 12 million that will be added in the next three years. What could potentially be of great relevance and importance to LSPs the world over in this piece of news is the fact that these SMEs contribute an extremely healthy 40% to the total exports of the country. Viewed from a global perspective, that would mean a potential market of over 40 million businesses for LSPs, because no export-intensive Indian SME can actually afford to have a monolingual business or product. But reality on the ground paints a very different picture. It is not uncommon to find Indian SMEs desperately concealing their linguistic discomfort, selling products at international trade fairs, hoping the quality of their products will do the trick. There is an SME at probably every nook and corner of India. These companies typically have great ideas and great products but only basic packaging. Language as a component of packaging is usually most conspicuous by its absence, ensuring that these offerings stay largely local in their reach and appeal. Monolingual SMEs have, for a long time, also been the true torchbearers of innovation in India. Take the case of ReliScore, a portal started by two ex-IIT students. Finding the right person is always a challenge in the corporate world. Resumes and grades, on the basis of which employers form their judgments, can both be equally deceptive. However, there are a significant number of candidates out there who are good at what they do and yet are never discovered only because they have not been able to perform well in exams, have frozen during HR interviews or are proud owners of unimpressive resumes. Now, this is not really an Indian problem. I have been present when dozens of employers in the western world complained about this very problem. This is where ReliScore offers a great fit. It offers a seamless platform for professionals to showcase their skills to potential employers. I�m just wondering if the people at ReliScore ever considered that employers and potential employees in the whole of Europe could be a potential market for their portal, should it ever be localized into a few European languages. As opposed to ReliScore, take the example of Multi Crafts, an SME in the business of manufacturing high-quality fiber reinforced composite laminates. The owners had their eyes set on the European market. The LSP suggested first localizing the website and other sales literature into Italian, the language of their primary market. The LSP also suggested writing the first paragraph of the sales e-mail in Italian. The first paragraph said that there was nobody in the organization who could speak Italian but that potential customers in Italy could read about the company�s products on its website in Italian, and though the staff would prefer to correspond in English, they welcomed any e-mails that were written in Italian. In two quarters, the company registered an impressive 30% increase in the number of enquiries from Italy in particular and Europe in general. Its website is now localized into two more European languages. So, clearly, there is a world of opportunity knocking at the doors of LSPs, even in these times of financial turmoil. If some markets have stagnated, some others have opened up. The story of India could be the story of, pretty much, any emerging market in the world. Much like that intelligent investor who buys when markets fall and then buys some more when they fall some more, LSPs must make the most of these difficult times to explore new markets and acquire newer customers. And although the Brazilian samba, Russian roulette and the Chinese dragon are all thrilling options, there is nothing quite like embarking on this exciting odyssey by riding the Indian elephant!

Documenting with PI-Mod

Thu, 01 Dec 2011 00:00:00 +0100

The introduction of an XML-based documentation system requires multifaceted planning and far-reaching decisions. To give an example, the selection and introduction of special content management systems for technical editing was described in detail in the tekom CMS studies of 2005 and 2008 [1]. As well as IT project management, these studies explain the preparatory planning work that has to be performed within the company. This work can be summarized under the term "content engineering" and contains decisions on the structuring of information, on modularization and variant management, and on rules on phrasing and formatting. Such rules have to be developed or introduced on the basis of standards. The selection of a suitable information model is particularly important for XML applications because it maps most of the specified rules. The XML structure elements it contains provide the structural grid for the entry of text. Phrasing samples and, ultimately, the options for publication are coupled to the information model and must be adapted to the requirements of the respective type of information.

 No consistent model so far

In spite of efforts to achieve standardization, there is no established consistent (XML) information model that meets all the needs of structured information gathering. Differences between the structures for possible types of information, products and target groups seem too great. The 2008 study also showed that around half of all documentation was drawn up without actual structuring or modeling at that time. Around a quarter was created with structures specific to a company or system. The remainder in the German-speaking area was shared evenly between several standardized and public (XML) information models such as DocBook, DITA and S1000D. CMS providers also usually provide system-specific information models. These models come from customer projects and have been optimized over the years for use in the respective systems. With the exception of larger companies, XML applications are still in the minority when it comes to editorial tools and systems. However, interest in such applications seems to be growing, especially in small and medium-sized businesses. A new internal method for structuring information ought to be tackled at the same time. Existing standardized information models come from specific industries and applications such as software documentation or documentation in aviation or the military [2]. No information model has been established as a standard or quasi-standard for plant construction and mechanical engineering and the user and service information involved. In the past, the majority of CMS projects in the German-speaking area was implemented in exactly this environment or related areas, usually as system-specific implementations or individual solutions. Unfortunately, the attempt of the VDMA to establish the "mumasy" information model did not have a widespread impact.

The concept

It therefore seemed appropriate to define a structure based on the experience gained in mechanical engineering that could be of general use as an open information model. One of the mentors was the structure of the LIEBHERR Group, which has been in operational use since 1997. In 2008, several companies and consultants defined the new "PI-Mod" information model in real projects under the general management of Prof. Ziegler. This model allows contents to be entered in modular fashion - hence the "Mod" part of the name - in broad areas of plant construction and mechanical engineering as well as in related industries (automation, electronics, consumer products). One very important goal was to provide a structure that would be easy for CMS providers to implement. For example, it was necessary to keep implementation details "open" in those places, which empirically are implemented differently in every system; examples include mechanisms for cross-reference and reuse. At the same time, the intention was to cover in particular the specifics of the industry, i.e. the information structures typically required there. These are included by means of semantic elements, i.e. structures such as technical data or maintenance plan information that are named according to their function and application.

Product and information qualification

The "PI" in the name is used not only for its association with a "circular" method of documentation, but primarily for a classification of modular contents that is necessary in practice. During module planning or content engineering, meta data are allocated to the modules in order to enable them to be stored and found. In addition, the intention is to enable further processing of publications and information. Meta data usually map the product classification ("P") and information classification ("I"). The corresponding XML attributes in the modules are therefore named "prodclass" and "infoclass". Like in many design-based classification schemas for components or their product or function structures, these attributes can be applied hierarchically in order to map interdependent meta data. The same applies to the classification of information types. The multi-level meta data of the information classes often result from the normative structuring of operating manuals and the specifications from the Machine Directive. The abbreviated version of the method of "PI classification" used here is independent of any specific information model and is suitable for general use in editorial systems [3]. The following table contains typical examples of PI classifications in different modules. Module 1 contains the composition description for an inking roller in a company-specific partial hierarchy, while module 3 contains the assembly instructions for a longitudinal cutter. As every CMS project - or, to be more precise, every product and every industry - requires different meta data values, these are not part of the PI-Mod standard as a whole, but are instead created as respective company-specific values ("customizing"). Providers and implementers of systems have extensive experience in this area, and this experience can be suitably implemented here.The classification of the information to be recorded is also reflected in the descriptive names of root elements of modules. In total, the current information model contains seven module types, which are depicted in figure 1. The uppermost level of information-related meta data therefore corresponds to the module types in the example. PI-Mod uses English terms such as "descriptive". Fig. 2: Seven module types in PI-Mod; the mod element serves as brackets for the module types. PI-Mod takes into account the "classic" descriptive and instructional information recorded in the two main module types:

descriptive, which is used, among others, for composition and function descriptions, technical data and general descriptions
task, which is used for instructions for individual steps

In addition, there are five more module types that accommodate the specific requirements of the industries mentioned:

diagnosis, for simple troubleshooting
taskintervals, for maintenance plans
tools, for tool lists and operating equipment
lubrication, for lubrication plans
glossary, for glossaries

Every module type has its own, functionally motivated sub-structure, which is largely formulated semantically, i.e. using descriptive element names. This means PI-Mod can be combined with structuring methods such as function design and language control tools. Modules can then be used to fill specific publication structures. Instead of providing a specific aggregation structure and fixed referencing mechanisms, the standard provides the numerous system-specific freedoms required. This is exactly the point where the working methods of CMS differ greatly. However, due to the uncomplicated hierarchical interlocking of modules, PI-Mod makes it possible to use a multi-level publication structure that is suitable for a great many document types. The modular approach and meta data structure also allows other applications to be implemented, such as portal access to component information or other mobile and electronic applications.

Special mechanisms

The model also offers further special features, including the "collections mechanism" and the tagging of technical or physical parameters as numerical values and units. The latter allows the automatic conversion of tagged units from metric to imperial, for use in the US, for example, or vice versa. It is also possible to enter both systems of units and process them manually or filter them by market. All these options occur in practice, so they should be supported by an information model and its implementation. The collections mechanism is also designed to be suitable in practice. It is, for example, possible to provide information on the frequency and responsibility relating to maintenance tasks within the task module, and using the taskinterval semantic element. This information is gathered automatically during publication and then output as a structured maintenance plan � figure 2.

Fig. 3: Schematic illustration of the automated publication of maintenance tables by means of the collections mechanism - maintenance intervals are recorded in the task module with the taskinterval XML element and then collated for publication in the taskinterval module; bottom: maintenance table in a PI-Mod implementation, sorted according to components.

Conversely, it is also possible to record custom taskinterval modules separately as a part or as complete maintenance plans. Next to the semantic structures, it is also possible to use manually-entered tables. This also makes it possible to use a mixture of various working methods in the content management environment. The recording and publication of tool lists and working materials (tools) or lubricants (lubrication) is organized according to the same principle. The remaining module types, "diagnosis" and "glossary", are designed for troubleshooting and error tables (messages, causes, remedies) and for glossary entries and overviews in publications.

Adjustments

Even though PI-Mod was developed as a standardized information model, its design and technical implementation allow for additional customizing options. That is why the PI-Mod packages for DTD and style sheets consist of a central "core" and a "custom" part. The core provides the structures, elements and attributes defined as the technical core. These are used in the custom DTD to provide a best-practice project implementation that is capable of running in the standard. Where necessary, it can be customized flexibly by means of a simple overwriting, deleting or creating mechanism. Thanks to the separation between PI-Mod concepts and implementation logics, it is possible to consider and implement customer and system-specific requirements. The procedure for customizing was defined methodically and documented comprehensively. It is possible, for example, to integrate additional standard features from newer versions of PI-Mod in current projects in spite of any adjustments made [4].

Tools and services

PI-Mod was quickly met with interest by CMS providers and users. From 2008, it was implemented in the first live projects and provided the basis for the current version 1.2. This is available on the internet as an open-source application.

The PI-Mod information model as document type definition, DTD
The element reference can be used as part of an editorial guideline
Style sheets for the formats XSL-FO/PDF, CHM, HTML
The documentation of the methodical PI-Mod customization
An environment for XMetaL

The website also contains a current overview of content management systems that provide PI-Mod as standard or as an extension. The information model can be used free of charge and is only subject to one license which must contain a reference to the source. Service providers and providers of CMS can perform their own customizations or implementations independently from the PI-Mod working group. This will allow consultation on the use of PI-Mod to be offered as a service in future. As is usual for free projects, the working group is based on feedback, and on support from users and interested persons.

Conclusion and outlook

Until now, the reaction to the information model has been positive, even though it is still in its initial stages. However, acceptance at well-known companies such as ABB STOTZ KONTAKT and Koenig & Bauer shows that the benefits of a standardized information model are convincing: a fast and cost-effective implementation of methodical and technically tried-and-tested structures. The long-standing desire in mechanical engineering of allowing data exchanges between companies in the supply chain can be met in technical terms with such concepts and information models. Further developments are requested and planned for the (mechatronic) coupling of existing documentation with machine-linked software and control components as well as for training documents. Software documentation as supported by the DITA implementation is not a focus of PI-Mod. These two information models actually complement one another. The PI-Mod developers have so far not favored applications without CMS, as both methodical (PI classification) and technical knowledge (XML/XSL) is required, and this is only available in individual cases in the target industries. However, in many cases it is possible and sensible to test the modular and XML-based documentation in terms of a "proof of concept" under supervision prior to the introduction of a CMS. PI-Mod provides the entry and publication options required for this purpose. Additional editor support is being prepared, including for Adobe InDesign. Further organizational design is still open. Different concepts are possible for the long term; the structure could be maintained by a consortium or an association, for example. In general, the principle is that cautious technical development is preferable to marketing-driven hype.

Bibliography

[1] Straub D., Ziegler W. (2008): Effizientes Informationsmanagement durch spezielle Content-Management-Systeme. (Efficient information management through special content management systems) [2] Kr�ger M., Ziegler W. (2009): Standards f�r strukturierte technische Informationen � Ein �berblick. tekom Hochschulschriften, Bd. 16. (Standards for structured technical information - an overview. tekom academic journals, vol. 16.) [3] Drewer P., Ziegler W. (2010): Technische Dokumentation � Eine Einf�hrung in die �bersetzungsgerechte Texterstellung und in das Content Management. (Technical documentation - an introduction to creating texts suitable for translation and to content management.) Vogel Verlag. [4] Steurer S., Ziegler W. (2010): PI-Mod in der Praxis � Einsatz und Anpassung des Informationsmodells f�r das Content-Management. (PI-Mod in practice - using and customizing the information model for content management) Conference transcript, tekom annual conference.

A reading guide makes it easier

Thu, 01 Dec 2011 00:00:00 +0100

Depending on the amount of text and the information needs of the reader, reading a manual is similar to short or long distance running. Long before the race kicks off for the reader and he starts his manual run, we plan the route, highlight the entry points, define goals, secure the route and provide road signs. However, despite careful planning, anything may go wrong during the run. Even the fitness of the reader plays a role. But much would be gained, if technical editors create the best possible conditions for a successful manual run.

Planning the route

Before we start writing the manual, we plan the thematic route and divide it into more manageable sections. This lets the manual reader cope with the distance later, without running out of steam. We fix our route plan in a table of contents, which is, however, not the end of it. During the follow-up, we must check and re-check the route: for example, for directness, practicality or stumbling blocks and other safety risks. If necessary, routings must be corrected, more practical ways must be adopted and risks eliminated or secured alternatively. Failure to apply these measures may result in such contents:

1. General Features
1.1 General Operating Information
1.1.1 Screen Masks
1.1.2 Input Media
1.1.2.1 Alphanumeric Keyboard
1.1.2.2 Touchscreen
1.1.2.2.1 Operation
1.1.2.2.2 Button Assignment
1.1.3 Special Features
1.1.3.1 Warning Signals
1.1.3.2 System Messages
�

On checking this route, it is immediately apparent that the section �General Features� ends with the section �Special Features�. This is anything but straightforward and can irritate the manual reader at the least. If the reader selects the �General Features� section, he certainly does not want to land at Special Features, just as we do not want to find ourselves in the forest during a city tour. And that is just where the planner of the above route got lost by missing the forest for the trees. This is partly due to the complex heading hierarchy, which exceeds the recommended three hierarchical levels by far. No one can understand this then, neither a technical editor nor a reader. However, the technical writer was not completely wrong, as the information about �System Messages� and �Warning Signals� definitely belongs to �Operating Information�. As usual, the sticking point lies in the structuring and formulation, whereby, well thought out formulations simplify the ordering of the topics. We can change terms, for instance, make the forest into an urban forest in the city tour or turn the "General Operating Information" into "User interface". Sometimes it is also enough to remove unnecessary terms like "Special Features". Ultimately, the table of contents could look like this:

1. Operating information

1.1 User interface

1.1.1 Screen masks

1.1.2 Buttons

1.1.3 System messages

1.1.4 Warning signals

1.2 Input media

1.2.1 Keyboard

1.2.2 Touchscreen

Marking the starting points

The manual reader himself decides which sections he wants to read. To simplify this choice and the section overview for him, we highlight a starting point for each section using headings. The clearer the starting point, the easier it is for the manual reader to find them and fewer "false starts" can be expected. Among other things, a starting point is clear if it stands out well from the others at the first glance. Under this aspect, the following headings have failed:

I. Dimensioning of the solar generator

II. Dimensioning of the cable cross-sections

III. Dimensioning of the charge controller

Headings that begin with different and distinct terms are more effective:

I. Solar generator dimensioning

II. Cable cross-section dimensioning

III. Charge controller dimensioning

Starting point terms that the reader is familiar with facilitate the matter further.

Defining goals

One who starts somewhere usually wants to arrive somewhere. So does the manual reader. Apart from his overall goal to operate the product described in the manual successfully, he has a series of intermediate goals in mind, i.e. to overcome some problems with the product. But for him to start in a targeted manner, he needs to know what the end goal is. Headings help in this task by not only providing distinct starting points, but also identifying the respective goal clearly. Moreover, they make it easy for the manual reader to choose his section, because he can compare his own goals with those provided, before starting. Take the topic "Software Installation". Some only want to read about the basic installation issues in theory while others want to cut right to the chase and start with the practical implementation. Manual readers can thus have different objectives in the same issue. Purely substantive headings, as in the next example, seem more theoretical, allow descriptive text to be expected and give no indication as to whether the respective sections provide installation instructions:

1. Software installation

1.1 Installation preparation

1.2 Server installation

1.3 Client installation

Whereas in this version:

1. Installing software

1.1 Preparing for installation

1.2 Installing server

1.3 Installing client

Headings with verbs signal to the reader instructional contents in the chapter. Thus, if we consistently distinguish between instructive and purely descriptive chapters by using or not using verbs, we facilitate the reader's goal orientation.

Providing warm-up phases

Like all runners, guide readers must also warm up: prior to the whole distance as well as before the individual sections. We take this into account by offering introductions to the manual and to each chapter. This allows the manual reader to warm-up to the respective topic and prepare himself optimally for the upcoming run. For example, consider the following introduction to a chapter from a software manual for physicians:

Compare fixed values
Comparing fixed values is a basic feature of the drug information system. With the aim to prescribe the cheapest possible drugs, you can determine cheap alternatives for individual drugs by comparing the fixed values. For this, start a differentiated search for generic drugs with
� the same active ingredients,
� comparable active ingredients,
� comparable effect.

Proceed as follows:
1. �
2. �

And if there's nothing to say in the preface, the introduction can at least provide an outlook on what lies ahead, i.e. on the structure and content of the manual or chapter.

Increasing requirements gradually

In order to support the warm-up and not overwhelm the reader and let him rise to his top form, the performance requirements should be increased with caution. Therefore, the most difficult and demanding sections should not be right at the beginning. On one hand, we can generally precede the difficult sections with the easy ones, if the topic of the manual permits it and on the other hand, we should build up knowledge step by step through the information provided in the manual. Both approaches can be seen in the following table of contents, which comes from the instruction manual for an iron:

1. Connecting the iron

2. Switching the iron on and off

2.1 Switching on

2.2 Switching off

3. Ironing without steam

4. Ironing with steam

4.1 Filling the water tank

4.2 Ironing with constant steam

4.2.1 Ironing horizontally

4.2.2 Ironing vertically

4.3 Ironing with steam blast

Take for example, section 3. In contrast to the subsequent section, it is not complex and therefore apparently easier. In addition, section 3 gives basic knowledge, which section 4 can build upon.

Setting milestones

Milestones help the manual reader to keep his bearings during the run. The following, among others, can be used as milestones

Headers with lively running titles that contain the chapter and section headings
Highlighted key terms or keywords, ideally as side headings in a marginal column
Symbols and other graphic design aids
Operating results in text and image, from which manual readers can closely monitor whether they are still on the right track
Characteristic paragraph formats

Consider an example of the numbered list as a proven paragraph format for step-by-step instructions or blocks of statements. It meets several orientation features at the same time:

As a unique identifying feature, the numbering makes it easy to spot the step instructions within the remaining text
The number of points or numbered steps provides information about the length of the respective operation
The number of the last executed operation step tells the reader how much of the operation he has already completed and how much still lies ahead
And should he pause once, he can easily remember from which step he needs to continue later, based on the numbers

Announcing branch operations

Not just milestones help the manual reader to find his way. The directness of the route is at least as important as it is to read with a view of the route plan. But not all routes are straight. Some routes branch out even in our instructions, e.g. in operation alternatives. Take this scenario: Mr. Bright has purchased lights that he wants to attach directly to the ceiling. He opens the supplied installation instructions, in which the following is stated:

The lights are supplied as built-in lights, which are designed to be mounted on a hollow box or a ceiling junction box.

Exception: Using the surface-mounted socket that is available as an accessory, the lights can also be mounted on solid ceilings.

Unfortunately, Mr. Bright is discouraged and gives up just after the first sentence, because he thinks the introductory statement is general and universally valid. Mr. Bright is upset and angry at the light seller. Had he not promised that the lights could be installed directly on the ceiling? And now it�s not possible? The second paragraph indeed has the answer to this, but our manual reader does not come this far. The bottom line is an unpleasant situation. And just for the reason that the technical editor unnecessarily hid an important assembly method behind a long mountain. Instead, he could have announced in the beginning itself that there is more than one way. Mr. Bright would have continued further carefully and found the following:

You can mount the lights in different ways:
� as built-in lights in the ceiling: using a conventional cavity junction box or ceiling junction box
� directly on the ceiling: using a surface-mounted socket which you can buy at your lighting retailer.

Securing the route

The route must be sufficiently secure so that the manual reader arrives safely at his goal and does not stumble on the way. In particular, warnings help, but not when they are just behind the stumbling point, as in this example:

Unscrew the vent cap from the casing vent

WARNING: Oil mist comes out when the vent cap is opened. Keep distance and do not inhale the oil mist under any circumstances.

With such an arrangement, the reader may not read the warning at all, because he is already �drowsy� after unscrewing the vent cap and it�s all over by then. The following version has an early warning:

WARNING: Oil mist comes out when the vent cap is opened. Keep distance and do not inhale the oil mist under any circumstances.

Unscrew the vent cap from the casing vent

The first thing is to put the warning before the �dangerous" operating step. Secondly, it must be ensured that the warning is not overlooked. Using symbols helps to increase the reading probability. This is especially true for readers who like to leaf through manuals quickly.

All clear!

Before we conclude our work, we should check the following points again:

Are the topics and the sections straight forward and clear?
Can they be handled with respect to the length and level of performance?
Are there enough warm-up phases?
Are the individual starting points easy to find?
Are the above-mentioned objectives clear and consistent?
Are there signposts?
Is the route secured?

Were you able to answer all the questions with yes? Then the manual can be released. And even if we as technical editors seldom experience how it goes for the reader, at least he will know where he is going � thanks to our reading guide.

Latest Articles on tcworld.info

Of power adapters and language quality assurance

The �lemon market� trap

What is Language Quality Assurance?

Building a comprehensive QA model

Applying the model

Assessing the overall quality of a document based on editorial comments

The problem

Why the usual methods do not work

The proposed solution

A few words of caution

Suggested Reading

Building a social network within an enterprise

Relationships

Influence

Identity

Privacy

Psychological elements of customer acquisition

Your own situation

The way to emotion

On the other side of the golf course

Effective sales arguments

When is it time for the discussion

Don�t forget existing customers

Collect arguments, define targets

Identifying your conversation partner

Self-praise is no praise?

Summary

Illustrations based on 3D CAD data

Version A � 3D illustration

Version A - Process and tips

Version A - Recommendations

Version B - 3D screenshots

Version B - Process and tips

Version B - Recommendations

Summary

Links to version A

Links to version B

Creating a good impression with the title page

The botched title page

An alternative

Interesting design - without text

Not always formal

And without the title picture

The title page in landscape format

Behind the title page

Conclusion

Setting up a comment feature for online Help

Advantages:

Disadvantages:

The basic components

Solutions in authoring tools

Solutions by providers

Advantages:

Disadvantages:

Commercial script solutions

Free script solutions

Expanding search

Conclusion

India offers new business opportunities

Documenting with PI-Mod

No consistent model so far

The concept

Product and information qualification

Special mechanisms

Adjustments

Tools and services

Conclusion and outlook

Bibliography

A reading guide makes it easier

Planning the route

Marking the starting points

Defining goals

Providing warm-up phases

Increasing requirements gradually

Setting milestones

Announcing branch operations

Securing the route

All clear!

Version B - Process and tips 

 No consistent model so far