Technical Writing Resources

Writing Exercises

2005-12-14T04:15:00.000-08:00

Writing exercises are a great way to both increase your skill as a writer and to generate new ideas for future work. They can also give you a new perspective on your current project. One of the great benefits of private writing exercises is that you can free yourself of fear and perfectionism. To grow as a writer, it is important to sometimes write without the expectation of publication. Don’t be afraid to be imperfect. That is what practice is for. What you write for any of these exercises may not be your best work, but it is practice for when you will need to write your best work.

Pick ten people you know and write a one-sentence description for each of them.
Record five minutes of a talk radio show. Write down the dialogue and add narrative descriptions of the speakers and actions as if you were writing a scene.
Write a 500-word biography of your life.
Write your obituary. List all of your life’s accomplishments. You can write it as if you died today or fifty or more years in the future.
Write a 300-word description of your bedroom.
Write a fictional interview with yourself, an acquaintance, a famous figure or a fictional character. Do it in the style of an appropriate (or inappropriate) magazine or publication such as Time, People, Rolling Stone, Cosmopolitan, Seventeen or Maxim.
Pick up a newspaper or supermarket tabloid. Scan the articles until you find one that interests you and use it as the basis for a scene or story.
Keep a diary of a fictional character.
Take a passage from a book, a favorite or a least favorite, and rewrite the passage in a different style such as noir, gothic romance, pulp fiction or horror story.
Pick an author, one you like though not necessarily your favorite, and make a list of what you like about the way they write. Do this from memory first, without rereading their work. After you’ve made your list, reread some of their work and see if you missed anything or if your answers change. Analyze what elements of their writing style you can add to your own, and what elements you should not or cannot add. Remember that your writing style is your own, and that you should only try to think of ways to add to your own style. Never try to mimic someone else for more than an exercise or two.
Take a piece of your writing that you have written in first person and rewrite it in third person, or vice-versa. You can also try this exercise changing tense, narrators, or other stylistic elements. Don’t do this with an entire book. Stick to shorter works. Once you commit to a style for a book, never look back or you will spend all of your time rewriting instead of writing.
Try to identify your earliest childhood memory. Write down everything you can remember about it. Rewrite it as a scene. You may choose to do this from your current perspective or from the perspective you had at that age.
Remember an old argument you had with another person. Write about the argument from the point of view of the other person. Remember that the idea is to see the argument from their perspective, no your own. This is an exercise in voice, not in proving yourself right or wrong.
Write a 200-word description of a place. You can use any and all sensory descriptions but sight: you can describe what it feels like, sounds like, smells like and even tastes like. Try to write the description in such a way that people will not miss the visual details.
Sit in a restaurant or a crowded area and write down the snippets of conversation you hear. Listen to the people around you — how they talk and what words they use. Once you have done this, you can practice finishing their conversations. Write your version of what comes next in the conversation. Match their style.

http://www.poewar.com/archives/2004/10/21/fifteen-craft-exercises-for-writers/

The Writing Process

2005-11-27T23:11:00.000-08:00

Writing is a process that involves at least four distinct steps: prewriting, drafting, revising, and editing. It is known as a recursive process. While you are revising, you might have to return to the prewriting step to develop and expand your ideas.

Prewriting:
- Prewriting is anything you do before you write a draft of your document. It includes thinking, taking notes, talking to others, brainstorming, outlining, and gathering information (e.g., interviewing people, researching in the library, assessing data).
- Although prewriting is the first activity you engage in, generating ideas is an activity that occurs throughout the writing process.

Drafting:
- Drafting occurs when you put your ideas into sentences and paragraphs. Here you concentrate upon explaining and supporting your ideas fully. Here you also begin to connect your ideas. Regardless of how much thinking and planning you do, the process of putting your ideas in words changes them; often the very words you select evoke additional ideas or implications.
- Don't pay attention to such things as spelling at this stage.
- This draft tends to be writer-centered: it is you telling yourself what you know and think about the topic.

Revising:
- Revision is the key to effective documents. Here you think more deeply about your readers' needs and expectations. The document becomes reader-centered. How much support will each idea need to convince your readers? Which terms should be defined for these particular readers? Is your organization effective? Do readers need to know X before they can understand Y?
- At this stage you also refine your prose, making each sentence as concise and accurate as possible. Make connections between ideas explicit and clear.

Editing:
- Check for such things as grammar, mechanics, and spelling. The last thing you should do before printing your document is to spell check it.
- Don't edit your writing until the other steps in the writing process are complete.

http://web.mit.edu/writing/Resources/Writers/process.html

Windows Terminology in other Languages

2005-09-08T22:42:00.000-07:00

Translate 230 Windows terms in more than 20 languages other than English.
msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwue/html/Wordlists.asp

Website: How Stuff Works

2005-09-08T22:39:00.000-07:00

For all writers - this website shows how almost anything can be explained to almost anyone. www.howstuffworks.com

Measuring Documentation Quality

2005-09-08T22:22:00.000-07:00

Good documentation will generally have certain basic characteristics or attributes that ensures its effectiveness as a means of communicating information to the reader. In this article we list various criteria that you can use to appraise the effectiveness or quality of documentation. While ultimately it is the degree to which a particular document matches the requirements of its targeted audience that determines its effectiveness, this set of criteria at least provides an objective means of measurement. More

HCi Journal

Six Sigma in the Technical Writer’s World

2005-08-29T22:20:00.000-07:00

What is Six Sigma?

- A system to continuously build quality into your processes and products
- A fact based, data-driven improvement system
- A company-wide commitment to quality

What Six Sigma is not:

- A magic wand to correct the ills of a company
- Yet another quality directive without substance
- A tool that can be handed to the workers and forgotten

In order for it to work in whatever form you use, Six Sigma must be used by everyone in the
company/division/section or it will not work. The managers have to be as dedicated to the
process, if not more so, than the everyday worker.

What is a Six Sigma project?

- DMAIC: Define, Measure, Analyze, Improve, Control
- DMAIC fixes existing processes
- DMAIC example: Getting information from a SME—

. You already have a process, but you know there are sometimes problems with the
process. So you would use a DMAIC project to help the process become better.

- DMADV: Define, Measure, Analyze, Design, Verify
- DMADV creates new processes
- DMADV example: Asking approval to come to the STC Conference—

. You may not have a process in place to ask your manager to approve and pay for your
trip to the STC conference. In this case, you would use a DMADV project to create the
process and ensure it would work.

Terms and Definitions

- customer: The person who will benefit from the project
- sigma: Standard deviation of a population
- CTQ (Critical to Quality): - A transformation of the customer’s needs into a measurable requirement for the process

Define

- When you scope a project; you find the problem you want to solve
- DMAIC example: Getting information from a SME—

. Define the process and look for the problems within it. Create a business case for your
project and pitch it to management

- DMADV example: Asking approval to come to the STC Conference—
Define the goal you want to reach. (create a foolproof plan to get approval to come to the
conference)

. Create a business case for your project and pitch it to management.
Define your team
. Develop a plan to create the process needed.

Measure

- You gather initial information to further refine the problem
- DMAIC example: Getting information from a SME—

.Create measurements to quantify aspects of the process. For example, accuracy of the
information, quantity you get from the SME as compared to other places, time spent
following up, and so on. The point is to have quantifiable (measurable) information

- DMADV example: Asking approval to come to the STC Conference—
. Gather information from your customers (yourself and your manager-types in the office)
what they would want out of the process.
. Create measurements for the information you gather
. Prioritize your customers’ needs

Analyze

- You look at your empirical data in a variety of ways to find possible solutions
- You examine several solutions to decide on the best one
- Using numbers, you will acquire management acceptance of the selected solution
- DMAIC example: Getting information from a SME—

. You might decide that one problem to be solved in the process is how the SME gives you
the information—the paper airplane over the cube wall just isn’t working. So that is what
you are going to try to fix.
- DMADV example: Asking approval to come to the STC Conference—

. You would identify what would be required to meet the customer’s CTQs
. Create several solutions to the problem.
. You would then look at each solution, and mathematically (there are lots of tools to help
with the decision-making process) make a decision.
. You also check the risks associated with the plan and create ways to mitigate them.

Tools take the personalities out of the decision-making process. It may mean the solution you
want is not the best for the problem. While your manager may have bought in to the project in Define (highly recommended) you can now show them what is going on and that what you are trying to accomplish is not just coming from you—numbers talk to managers.

Improve

- You change the process to eliminate the problem
- DMAIC example: Getting information from a SME—
- Remember the paper airplane over the cube wall just isn’t working.

. So you come up with some other solutions, like email, face-to-face meetings, and so on.
. You then look at each solution, and mathematically (there are lots of tools to help with
the decision-making process) make a decision.
. You then do a couple of test runs to see if your change makes a difference—take
measurements, and compare them against the original ones. Let’s say you find that the
face-to-face meetings give you the best results.

Control

- You monitor the process to ensure that you have selected the best solution
- DMAIC example: Getting information from a SME—
. You make the face-to-face meetings part of the information-gathering process
. You create ways to fool-proof the plan (write up your process, teach the SMEs what
you’re doing, and so on)
. You continue to take measurements to be sure that the solution continues to work.

Design

-You design a solution to the problem based on the empirical data you have gathered
- DMADV example: Asking approval to come to the STC Conference—
. You create the detailed plan of how you are going to accomplish the solution decided on
in Analyze
. You revisit the risks associated with the plan, make sure you have mitigated the ones
identified earlier, and not created new ones. (script not allow for male managers, script
not adaptable for others to use, etc.)
. You create a verification plan to test the process and make sure it works before you use it
(perhaps to hand the script to a coworker with a different manager and have them walk through
it)

Verify

- You run a test of the design to ensure it is the best solution to the problem
- DMADV example: Asking approval to come to the STC Conference—
. You use the verification plan and measure the effectiveness of it in several quantifiable
ways (got expected result, time taken to learn script, adaptability of script, and so on)
. You evaluate the performance of the design based on these measures.
. You implement the design and hand the process to whoever will tasked with its upkeep

Case Studies

Case 1: Background

· Needed to start using Six Sigma
· No previous contact with customers
· Decided that designing a survey to get feedback form the customers was a good place to
start
· Used DMADV because it was brand new

Highlights

· The scope was scaled back to include just the creation of the survey to fit the timeframe
in which we had to work
· Talked to the customers of the project (tech writers) and found out what they wanted to
know
· Drew up a survey that would meet those needs

Results

· Selecting a team is as important as the project itself
· Users wanted paper manuals for complicated configuration tasks
· In-house terminology was not the same as the users’ terminology, creating complications
and confusion

Case 2: Background

· New functions in the manual overlapped older functions
· Opportunity to make manual easier to use
· Used DMAIC because it was reworking an old manual

Highlights

· Talked to customers about the manual as it stands
· Incorporated the new information with the old, and reworked the manual’s organization
· Gave the new manual to the customers to see what they thought
· Measured their response

Results

· There was much about the manual that they did not want to see changed
· What was changed helped the manual to be even better than before
· Even when the customer may not see a process as broken, it can still be improved

Case 3: Background

· Acquired product that had no formal manuals
· Current product’s documentation style was not consistent with the rest of the business
· Decided to create new styles to bring this product up to speed with the rest of the
business’s products
· Used DMADV because we were starting from scratch

Highlights

· A chance to talk with customers—get their input
· Put together new templates and a game plan based on their responses
· Currently in process of finding out whether we met their immediate needs or not

Results

· Users wanted the step-by-step first and foremost
· When we get pushback from others to write something else, we have the customer’s word
help state our case
· We predicted that once the need for basic procedures was met, the users would ask for
tips, hints, and other niceties

Case 4: Background

· New product needed a help system
· Wanted to look at single-sourcing as a way to save time
· Used Six Sigma to choose a product that would work for us
· Used DMADV because it was a new process we were designing

Highlights

· Determined what we (and other customers) needed
· Tested a couple of systems out, compared them to our criteria
· Took our findings to management, and with their input, made a decision

Results

· Working towards single-sourcing allowed us to show savings in time and money to our
managers
· The solution we were leaning towards was not the best once we heard management’s
input

Conclusions

Six Sigma…
· can assist in making design decisions
· can ensure the documentation is satisfying the customer
· can show managers where the documentation is improving
· may take time up front to set up and get the data, but can save time and money overall

Lori Beard and Erin Welch, Technical Communicators

Job: Content Writer, Lahore

2005-08-10T21:24:00.000-07:00

We are looking for candidate who can produce content for our quarterly newsletter on various outsourcing related topics especially Accounting, IT. The candidate should have excellent English writing skills. Please include some writing samples (as doc files) and link to online portfolio. Those who will email only resumes without cover letters, writing samples and minimum salary expectations will not be considered.Please send your CV’s to:jobs@technobeavers.com

TechnoBeavers
84-G, Gulberg 3
Lahore, Pakistan
http://www.technobeavers.com

STC Documentation Awards

2005-08-04T05:38:00.000-07:00

STC Documentation Awards are for those who value the opportunity to have their English language documentation recognised as clear, concise and effective. There are two categories - printed documentation and online delivery. Entry for the awards is straightforward and the deadline has been extended to 15th August. Entries must have been issued between April 2004 and July 2005 and ISTC membership is not required. It’s a chance to see how you measure up to your peers! See details: http://www.stc.org/internationalCompetitions.asp

The Key for Effective Documentation

2005-07-25T21:37:00.000-07:00

To successfully communicate to users, documentation must do more than meet the user’s information needs, it must present the information in the same way the user processes the information. The design of software and it accompanying documentation must be reconceived so that the design is done from the problem-solver’s point of view. Effectively designing documentation requires the writer to: start with the user, answer the user’s rest questions, optimize all documentation as a single unit, allow for user mistakes, and consider how you present the information.

“The ability to create effective verbal and visual information for people to use according to their own needs is at the heart of the communicator’s role.” (12, p.38) Here lies the holy grail of effective software documentation. However, as long as the developer sees software as a series of screens with fields optimized to access a database, as long as the technical communicator sees it as a series of screens to be described field by field as long as senior management sees it as a series of reports that they needed yesterday for answers they need today, as long as IS management sees it as a steadily decreasing budget item, as long as users see it as something new they’ll have learn and something which may cost them their jobs, the holy grail will remain hidden in the mists.

We need to stop considering documentation, software interface, and online help, as separate entities and remember we are communicating with users. We must go beyond simple instructions and design documents that assist in solving real-world complex problems. We need to support the problem-solving strategies that address the user’s real tasks. Documentation for complex tasks means thinking big; it means considering and integrating everything the user sees: user interface, online help, error messages, and paper manuals. To accomplish this goal, we must do more than think about a program’s menu structure; instead, we must follow a different path.

Documentation researchers need to discover the conditions and real workplace tasks that require a user to consult a manual to make up for a poor interface and require document designers to become involved in interface development, online help design, or organizational training. (10, p.83).

To successfully communicate to users, documentation must do more than meet the user’s information needs, it must present the information in the same way the user processes the information. We can change appearances, but effective communication does not lie in appearances. Communication works at the level of assumptions, implications, and expectations. Effective communication means determining and providing answers to the complex problems of the real-world. Analysis should be stated “in terms of the behavior-shaping goals and constraints that define the boundaries of a space guided by their local and subjective performance criteria” (11). Dobin insists that to support problem solving for open-ended problems we must gain an in-depth understanding of the user and not the software. “The user’s vocabulary, the user’s reasons for looking things up, and the problems the user confronts must be clearly anticipated’ (3, p.89). Actually, if we define the conditions and real workplace tasks early in the project and then use that information to design an interface meeting the user’s needs, the job of the technical communicator becomes much easier.

We no longer must fix a poor interface with documentation. Instead, we are create documentation the helps the user solve real-world problems by putting the right information in the right place at the right time in the right format. To put this in different terms: give users exactly what they need, when they need it—no more, no less. In this article, I discuss some points we must consider to decide how to provide the right information at the right time.

What must we do?

The design of software and its accompanying documentation must be reconceived so that the design is done from the problem-solver’s point of view. People are faced with many complexities and obstacles in performing a job and have developed many different strategies in overcoming these obstacles. We must acknowledge these obstacles and strategies and create documentation that minimizes them. Most of the current documentation that I see ignores these obstacles and strategies. Rather than address complex problems, current documents center on routine tasks; each menu option of the program exists in its own world, never connecting to any other option.

This is task-oriented documentation from the program’s point of view, not the user’s point of view.
The differences arise from how programmers and users view software. The programmer, viewing the software with an inside-out perspective works with a bottom-up method and sees a set of disjoint screens that interact according to the program specification. The user, on the other hand, works with a top-down problem solving method and views the software with an outside-in perspective, brings to the program a conceptual schema of how it works. When these two views are excessively out of sync, the program and documentation fail to be usable.

One of our most important jobs as technical communicators is to ensure these views don’t get out of sync. We must become, in Bowie’s words, “information engineers”. An important consideration of information engineering is to take a good look at the application. You need to determine and answer the questions going through the user’s mind while using the software. Carroll et al. found that people already understand the task-relevant concepts of the program. It is because of this understanding on the user’s part that we should strive to create designs that directly address user tasks in user terms. Users already know what they want to do, it is our responsibility to ensure they can easily accomplish it.

Techniques for good information engineering

Start with the User at the Beginning: It falls upon the technical communicator to help ensure the user is represented during product design. (Getting the technical communicator represented during design is another story.) Apply the user’s complex problems against the system design requirements to gain an understanding of how to support the relationship between them. When you decide what to write on a process, decide which parts of the process are really needed. As a result, you define which parts really need documentation. Otherwise, you are only doing outlining and doing neither audience analysis nor task analysis. As Spyridakis and Wenger state, everything must be considered: “We carefully consider our intended reader’s knowledge, experience, situation, and culture; we then seek to match the style, content, and design of a document to the tasks, needs, and desires of various readers” (13, p.202).

Answer the User’s Real Questions: Complex tasks involve more than single program options or tasks; they involve the real questions asked by the user. A simple task involves a single menu option and most current documentation posses it in terms of the program (Using the xxx function). A complex task is the complete piece of the big action. The complex task typically involves a question posed in terms of the user’s job and requires the use of several menu options. People sitting before a computer program don’t ask “how do I use this Frame option?’ they ask “is there anyway to get this block of stuff over there?’ As such, answering the user’s real questions means creating documentation using user terminology and containing procedures using multiple menu options.
Consequently, the documentation will not fit neatly into the software organization. However, this will be truly task-oriented from the user’s point of view and will allow the user to quickly find the necessary information. Do not be afraid of overlapping information. The same procedure or concept may appear in multiple places. In a highly integrated business environment, answering the question may even require using more than one program. The common design method of defining and considering each menu option as independent of all other functions does not and never will answer a real-world question.

Optimize Documentation as a Single Unit: The move toward single source documentation, with the same text appearing on paper and in online help, while helpful to us as writers, may not be useful to the user. If our goal is putting the right information in the right place at the right time in the right format, then we must consider exactly what we are putting in each place. No one seems to argue that paper manuals, online context sensitive help, and online reference each perform a different job and is used in a different way. Yet, they often each describe everything, instead of concentrating on what they do best. Think about the strengths of each and how they can help solve the user’s complex questions, then decide where to address that question and only place what is needed to solve that question in that section. In other words, globally optimize across everything the user sees instead of optimizing each part individually.

Remember that Users Make Mistakes: Most computer users want to get on the machine and use it to solve a real task right away. They do not want to spend time learning how to use the program. By doing so, the users will make mistakes. The documentation must address how to fix those errors.
Writers need to concentrate their task analyses more on likely errors that users may commit. Task analyses, therefore, should depart from an error-free perspective and instead focus on task complications and strategic responses, that is, on the inevitability of committing errors and ways of getting out of them. (9, p. 220)

Accept that errors happen and design efficient ways of correcting them from the beginning. (Think of how many times you referred to the documentation because something wasn’t working right and all it told you was to push the button you had pushed.) As the users become more familiar with the system, they rely more on memory and the number of mistakes may actually increase, although they accomplish the task quicker. (7,5)

When you start thinking about error correction in overall design, the flavor of the documentation changes. Rather than only containing error-free procedures, it addresses error correction; good documents address the procedure’s limitations and its common mistakes.

How the Information is Presented Matters:Information presentation has major effects on people’s decisions; depending on the presentation, they may actually make opposite choices and believe them to be best (14,6). Thus, presentation of information becomes the crucial factor in maintaining the flow of information (8). When people look at information, they tend to see what they expect to see. Unfortunately, getting them to see what we want them to see is often complicated by concepts of how a previous program worked. Duin claims that documentation “that is poorly organized will not elicit the appropriate schemata from the reader’s mind.” As a result, the reader voices the commonplace complaint about unusable documentation.

Also, the presentation format can actually change the way users use the information. Slavic found that users tend to change their assessment strategy to fit to the presentation method, rather than transform the information to fit a better assessment strategy. Thus, changes that make it easier to process information also increase the information’s impact. Problems occur when minor, but easy to present information, occupies too much of the design and, diminishes the salience of important, but harder to present, information.

Remember, the Interface also Communicates:Inconsistent design can significantly reduce a user’s perception of the intuitiveness of the software. This forces users to focus on relearning how to accomplish the task, rather than concentrating on the task itself. Remember that a user interface has two logical parts. The first, the physical interface with the buttons, windows, etc., is by far the easiest. How to design this part of the interface is the focus of books on user interface design. The second part of the user interface is the content. This is the content, use, order and actual text of labels on the entry fields (as opposed to the placement/font), the error messages, and the help text. It also includes the larger view of the interrelation of screens and components of the program.
Helping users solve real-world problems means focusing everything the use sees on the user problem and not on the easiest way to program/write it. Programmers often concentrate only on the interface layout. That part is easy and they have set guidelines. But a consistent user interface is not sufficient to make a program usable.

The interface layout and content must be combined and the failure of either reduces the overall effectiveness of the program. It also causes excessive amounts of documentation, either online or, most likely, paper to be generated in an attempt to fix the problem.

When everything communicates effectively

With the wide spread use of Microsoft® Windows®, the interface of the PC user has become much more consistent. However, the content of the program and documentation still varies from program to program. As such, while users understand how to point and click in the program, they still don’t know what to point and click or what to put in the blanks. One measure of successful communication is having users finish the interaction and feel they have smoothly completed their task. Feelings of having finally squeezed the results out of the system or of inferiority because they had to ask other people should not occur. To maximize user productivity we must break with the current writing methodology of addressing each menu option separately and address complex problems. Our documentation must provide the methods for accomplishing the complex tasks and provide answers to the real questions users ask.

We must go beyond simple procedures and create documents which assist in solving complex problems.

Michael J. Albers, http://www.stcsig.org/usability/newsletter/0505-effectivedocs.html

Information Architecture Standards

2005-07-21T23:41:00.000-07:00

In technical writing our focus is on being clear, concise, consistent, correct and complete. While at this, we are unconsciously thinking about content structure, organization, navigation, and access. We are, in fact, thinking about information architecture. As Mir G. Haynes says, “You do it, you just don't know it.”

Technical writers are increasingly taking part in managing large and complex documentation projects. Besides delivering content, they have to look at new ways to efficiently author and deliver content to meets user needs.

Technical writers should take a disciplined approach to structure content by closely tracking standards that are available for information architecture, information design and content management. They also have to study how other companies are implementing these standards and perform benchmarking studies to identify ways to improve content.

This article describes the following information architecture standards and methodologies that are applicable to technical documentation:

- Information Mapping
- DITA
- DocBook

Information Mapping

Developed in 1966 by Robert E Horn, Information Mapping™ consists of an integrated set of principles, techniques and standards for analyzing, organizing and presenting information.
Information Mapping enables writers to break complex information into basic elements for easy retrieval. To achieve this, Information Mapping requires that information is categorized according to its purpose under various information types such as Concept, Principle, Process, Procedure, and so on. It provides research-based principles for chunking and organizing information into modular units called information blocks and information maps so that it is easy to access, understand and remember. For example, Information Mapping borrows from George A. Miller’s research finding on the limits of human capacity to process not more than 7±2 chunks of information at a time. Information Mapping also recommends various ways to present the content for each information type.

Most of the principles, techniques and standards described in the Information Mapping method are not new to writers. However, a formal training on the Information Mapping method can help writers to quickly get adjusted to structured writing environments.

For more information on Information Mapping, see the following online resources:
http://www.infomap.com
http://www.namahn.com/resources/documents/note-IM.pdf

DITA

The Darwin Information Typing Architecture (DITA) is an XML-based architecture for authoring, producing and delivering technical information with a focus on information interchange and reuse.

DITA provides a generic topic type and proposes three other topic types—Concept, Task and Reference. It then lets you define additional topic types that are based on these topic types. This feature lets you create your own topic types to meet your information needs.

To enable reuse, DITA requires that topics must be able to stand alone so that they can be understood when they are encountered out-of-context, for example, when a user finds the topic through search, an index, or by following a link.

DITA maps enable different organization of topics for different documentation deliverables. For example, you can have a DITA map for a user guide and another for a training manual. Writers can use DITA maps to define the relationships between topics, to create navigational tools (hierarchical and sequential), or to add metadata to topics. The unique feature of DITA maps is that it lets you set the title and metadata for a topic in the context of its location in the topic hierarchy and for different deliverables. This lets you dynamically change the title for a topic in relation to its parent topic, and for each deliverable. Metadata can be used to identify a topic as advanced for one deliverable and basic for another.

For more information on DITA, see the following online resources:
http://xml.coverpages.org/dita.html
http://www-106.ibm.com/developerworks/xml/library/x-dita1/

DocBook

DocBook is a widely used system for authoring structured documents using SGML or XML. It was originally developed for authoring technical documents relating to computer hardware and software but can be used for any other type of documentation.

DocBook provides an extensive DTD of 300 plus elements that cover just about every conceivable technical documentation requirement. Most of the DocBook element names are easy to understand (for example, , , and ) and tell you what a block of text is. However, as most documents use fewer elements, there is a need to customize the DTD to filter out the elements that are not used.

If you are thinking of implementing structured writing and single sourcing in your organization, DocBook provides a standards-based, time-tested solution, and is supported "out of the box" by a number of commercial and open source tools. You can save a lot of time by not having to define your own DTD and creating the style sheets for single-sourcing your content to produce output in various formats.

For more information on DocBook, go to http://www.oasis-open.org/docbook/

Other IA Standards

Other information architecture standards that are applicable to technical documentation and related fields are:

Sharable Content Object Reference Model (SCORM) at http://www.adlnet.org
Structured Product Labeling (SPL) at http://www.fda.gov/oc/datacouncil/spl.html
ASD Simplified Technical English (formerly AECMA Simplified English) at http://www.simplifiedenglish-aecma.org/
S1000D at http://www.s1000d.org/
ATA iSpec 2200 at http://www.airlines.org/
Topic Maps at http://xml.coverpages.org/topicMaps.html and at http://www.topicmap.com

Summary

Though most of the information architecture standards are targeted towards structured authoring environments, the learning that we take away from these standards can be applied to traditional authoring environments. For example, the 7±2 information-chunking limit proposed by the Information Mapping method is relevant to traditional authoring environments also.

A study of various standards applicable to technical documentation and related fields and how they are implemented by other companies will motivate us to look again at the content we deliver and our authoring and delivery processes. A deeper understanding of our content and processes helps us to make intelligent decisions for improving the way in which we author and deliver content that meets our user’ needs.

http://www.stc-india.org/indus/042005/themeselva.htm

Largest Job Fair in Pakistan

2005-07-21T21:17:00.000-07:00

Pakistan Software Houses Association (P@SHA) has teamed up with Pakistan's leading job site, Rozee.com.pk, to organize a job fair of proportions never before seen in Pakistan. The job fair will feature company booths, exposure to high quality professionals and workshops that will give you the edge you want.Over 500 companies have been invited. This is a once in a life time opportunity to test your career's marketability. This fair will be advertised to more than 80,000 job seekers. Companies can find the best available talent from a huge pool of mid-level and high-level employees.

Workshop topics include:
» Resume writing
» Interviewing skills
» Communication skills
» Professional development

Don't miss this opportunity to improve your skills and network with representatives from a large number of companies from all across Pakistan. Entrance for this event is only Rs. 100 per person.However if you register online by August 15th, 2005, it's completely FREE.

Register Here

Job: Content Writer (Karachi, Pakistan)

2005-07-20T21:12:00.000-07:00

Clickmarks Pakistan is seeking a talented Content Writer to work in the product development group of the company. The ideal candidate will possess strong writing skills and the ability to gracefully handle a dynamic, fast-paced development environment.

COMPANY INFORMATION:
Clickmarks Pvt. Ltd.
Karachi, Pakistan
http://www.clickmarks.com

Job: Web Content Writer (Lahore, Pakistan)

2005-07-20T21:09:00.000-07:00

RDI Technologies is looking for a fresh-thinking copywriter who’s great at generating brilliant concepts as well as writing all types of marketing copy, as defined by the creative team, for online advertising, web content. We need an enthusiastic self-starter and a true collaborator that thrives on converting business strategies into effective marketing communications.

The candidate should be proficient at striking a fine balance between retail and strategic writing, articulate different voices with conciseness to capture different audiences, willing to take ownership of projects and drive them to fruition, able to work closely with web developer and designer in coming up with a visually and verbally compelling copy, and familiar with basic graphic issues.Major responsibilities include writing news / articles / blogs related to ISRAEL and IRAQ, so very much interested in candidates who are up for the challenge and can launch these projects successfully.

Qualifications:
- Should have at least 1 year of copywriting and creative experience in an ad agency, marketing department, or freelance capacity
- Bachelor’s Degree in Computers, English, Advertising, Journalism, Marketing, or other related areas of focus
- Superior writing ability and creative skills
- High-level problem-solving and analytical skills
- Ability to produce quality work within tight timelines
- Excellent communication and interpersonal skills

NOTE:
If you are a team player, have a great attitude, an artistic eye and meet the requirements above, please send a resume, cover letter, URLs of work that you have done to info@rditechnologies.net include some writing samples (as doc files) and link to online portfolio. Those who will Email only resumes without coverletters, writing samples and minimum salary expectations will not be considered.

COMPANY INFORMATION:
RDI Technologies
150 – B Garden Block,
New Garden Town,
Lahore, Pakistan
e-Mail: info@rditechnologies.net
WEb: www.rditechnologies.net

Job: Creative Writer (Permanent - Lahore, Pakistan)

2005-07-18T21:40:00.000-07:00

Write corporate profiles, marketing material, slogans, web copy/text, articles and other text requirements. Coordinate with marketing staff and other company executives.

Muhammad Bilal
Genex Business Solutions
78 Commercial Plaza, Cavalry Ground,
Lahore Cantt. (Near KFC) Lahore, Pakistan
http://www.genexbs.com

How to Handle Writer's Block

2005-07-13T00:20:00.000-07:00

It seems to show up only during our most stressful deadline-driven times and it stays until we find some way to show it the door. As writers, we all suffer from the insufferable writer's block. To the surprise of many, however, there are ways to overcome this problem and get back to doing what we love. Keep in mind that sometimes working through the problem requires you to get away from it. If you're having an episode, then try the following options and clear out those mental cobwebs now.

- Just Run: Exercising is a great way to let off some steam and stress. It gives you a chance to work through the anxiety that generally causes writer's block. Complement your workout with a pair of headphones and your favorite CD.

- Get some Sun: It's amazing what a little bit of sun can do for the mind. Take a short walk through your closest park or around the block. Getting in touch with nature lifts the spirits and helps you refocus by clearing your mind.

- Talk to a Friend: This is my favorite way of dealing with this problem. As a writer, I can't keep words in for very long so when the words don't come with ease I get agitated. Talking to a friend about my writer's block makes me feel as though I'm getting it out, in a manner of speaking. It's therapy without the bill and it really helps. Talk to a friend who understands how important this work is to you and spill your guts until you sigh with relief.

- Sleep and Eat Properly: Writer's block is nothing more than misdirected anxiety and stress. If you've been working endlessly, short on sleep or eating badly, it's possible your brain is just tired. Get at least eight hours of continuous sleep and eat some lean protein. If you're on a deadline then take a thirty-minute power nap and munch on a protein bar.

- Pick up a Good Book: Quit looking at your work and pick up someone else's. Sometimes it just helps to sit down, read, and get lost in a book by someone you enjoy and respect. It's as if you're letting your mind breathe and take something in as opposed to trying to get something out.

- Learn to Meditate: Meditating will not only help you clear up your writer's block, it will also help you feel better in general. Take a quick look at alternative medicine if you want some basic tips on how to get started. Now that you have read, meditated, talked and slept you should get back to work. Writer's block is just that - a block. Be patient and with these tips, you will soon have a handle on the problem.

Jessica Ramirez, http://freelancewrite.about.com/od/commonproblemsissues/tp/writersblock.htm

Micorsoft HTML Help Vulnerability, Security Update

2005-07-11T03:06:00.000-07:00

A new version of HTML Help was released in June 2005 to address a security issue. This article provides an insight of this issue.

What is the scope of the vulnerability?

This is a remote code execution vulnerability. If a user is logged on with administrative privileges, an attacker who successfully exploited this vulnerability could take complete control of an affected system. An attacker could then install programs; view, change, or delete data; or create new accounts with full privileges. Users whose accounts are configured to have fewer privileges on the system would be at less risk than users who operate with administrative privileges.

What causes the vulnerability?

The vulnerability occurs because HTML Help does not completely validate input data.

What is HTML Help?

Microsoft HTML Help is the standard help system for the Windows platform. Authors can use HTML Help to create online Help files for a software application or to create content for a multimedia title or for a Web site. For more information about how to create online Help files, visit the following Web site.

What might an attacker use the vulnerability to do?

An attacker who successfully exploited this vulnerability could take complete control of the affected system.

Who could exploit the vulnerability?

Any anonymous attacker who could display a specially crafted Web page to a user could attempt to exploit this vulnerability.

In a Web-based attack scenario, an attacker would have to host a Web site that contains a Web page that is used to attempt to exploit this vulnerability. An attacker would have no way to force users to visit a malicious Web site. Instead, an attacker would have to persuade them to visit the Web site, typically by getting them to click a link that takes them to the attacker's site. It could also be possible to display malicious Web content by using banner advertisements or by using other methods to deliver Web content to affected systems.

What systems are primarily at risk from the vulnerability?

This vulnerability requires that a user view Web sites for an attack to occur. Therefore, any systems where Internet Explorer is used frequently, such as workstations or terminal servers, are at the most risk from this vulnerability. Systems that are not typically used to visit Web sites, such as most server systems, are at a reduced risk.

Are Windows 98, Windows 98 Second Edition or Windows Millennium Edition critically affected by this vulnerability?

Yes. Windows 98, Windows 98 Second Edition, and Windows Millennium Edition are critically affected by this vulnerability. A critical security update for these platforms is available and is provided as part of this security bulletin and can be downloaded from the Windows Update Web site. For more information about severity ratings, visit the following Web site.

What does the update do?

The update removes the vulnerability by modifying the way that HTML Help validates data.

When this security bulletin was issued, had this vulnerability been publicly disclosed?
No. Microsoft received information about this vulnerability through responsible disclosure. Microsoft had not received any information to indicate that this vulnerability had been publicly disclosed when this security bulletin was originally issued.

When this security bulletin was issued, had Microsoft received any reports that this vulnerability was being exploited?

No. Microsoft had not received any information to indicate that this vulnerability had been publicly used to attack customers and had not seen any examples of proof of concept code published when this security bulletin was originally issued.

How does this vulnerability relate to the HTML Help vulnerability that is addressed by MS05-001?

Both vulnerabilities were in HTML Help. However, this update addresses a new vulnerability that was not addressed as part of MS05-001. MS05-001 helps protect against the vulnerability that is discussed in that bulletin, but does not address this new vulnerability.

For more information and security update click http://www.microsoft.com/technet/security/bulletin/ms05-026.mspx

Technical Writing: Style Guides

2005-07-07T23:22:00.000-07:00

The University of Chicago Press has announced the publication of the fifteenth edition of The Chicago Manual of Style, the essential reference on American English. "Those who work with words know how dramatically publishing has changed in the past decade, with technology now informing and influencing every stage of the writing and publishing process."

Apple's style guide is available online, as is the BBC News style guide. The BBC guide is written mainly for broadcasters, but would be of use for journalistic copy.

NASA's Web site contains a good general guide to grammar, punctuation and capitalization that will be useful to anyone who believes good writing isn't rocket science. You can download this guide as an Acrobat file.

Microsoft Manual of Style provides complete styles and guidelines for publishing a variety of technical publications. See this Web page on the Microsoft Manual of Style .

http://www.cherryleaf.com/news_free_microsoft_style_guide.htm

Operating Systems: Why Unix?

2005-06-07T21:48:00.000-07:00

What is an Operating System?

An operating system (OS) is a program that allows you to interact with the computer -- all of the software and hardware on your computer. How?

Basically, there are two ways.

- With a command-line operating system (e.g., DOS), you type a text command and the computer responds according to that command.

- With a graphical user interface (GUI) operating system (e.g., Windows), you interact with the computer through a graphical interface with pictures and buttons by using the mouse and keyboard.

With Unix you have in general the option of using either command-lines (more control and flexibility) or GUIs (easier).

Windows vs Unix: A Competitive History and Future

Microsoft Windows and Unix are two major classes of operating systems.

The Unix computer operating system has been in use for more than three decades. Originally it rose from the ashes of a failed attempt in the early 1960s to develop a reliable timesharing operating system. A few survivors from Bell Labs did not give up and developed a system that provided a work environment described as "of unusual simplicity, power, and elegance".

Since the 1980's Unix's main competitor, Windows has gained popularity due the steadily increasing power of micro-computers with Intel-compatible processors (CPUs), which is the platform that Windows was designed for. In recent years, however, a new version of Unix called Linux, also specifically developed for micro-computers, has emerged. It can be obtained for free and is therefore a lucrative choice for individuals and businesses on a budget.

On the server front, Unix has been closing in on Microsoft's market share. In 1999, Linux scooted past Novell's Netware to become the No. 2 server operating system behind Windows NT. In 2001 the market share for the Linux operating system was 25 percent; other Unix flavors 12 percent. On the client front, Microsoft is currently dominating the operating system market with over 90% market share.

Because of Microsoft¡¦s aggressive marketing practices, millions of users who have no idea what an operating system is have been using Windows operating systems given to them when they purchased their PCs. Many others simply are not aware that there are operating systems other than Windows. You, on the other hand, are here reading this article, and probably trying to make conscious OS decisions for home use or for your organizations. In that case, you should at least give Unix your consideration, especially if the following is relevant in your environment.

Advantages of Unix

- Unix is more flexible and can be installed on many different types of machines, including main-frame computers, supercomputers and micro-computers.

- Unix is more stable and does not go down as often as Windows does, therefore requires less administration and maintenance.

- Unix has greater built-in security and permissions features than Windows.

- Unix possesses much greater processing power than Windows.

- Unix is the leader in serving the Web. About 90% of the Internet relies on Unix operating systems running on Apache, the world¡¦s most widely used Web server, which is free.

- Software upgrades from Microsoft often require the user to purchase new or more hardware or prerequisite software. That is not the case with Unix.

- The mostly free or inexpensive open-source operating systems, such as Linux and BSD, with their flexibility and control, prove to be very attractive to (aspiring) computer wizards. Many of the smartest programmers are developing state-of-the-art software free of charge for the fast growing "open-source movement".

- Unix also inspires novel approaches to software design, such as solving problems by interconnecting simpler tools instead of creating large monolithic application programs.

Remember, no one single type of operating system can offer universal answers to all your computing needs. It is about having choices and making educated decisions.

Juergen Hass, http://linux.about.com/mbiopage.htm

Job: Technical Writer/Tester (Software) - Karachi

2005-05-25T21:30:00.000-07:00

Dear All,

We at Hauka Pvt. Ltd. require a Technical Writer/Tester(Software),
Who
is familiar with programing languages VB/VB.net. S/he will be
producing
technical specs and test plans/documents for the software components.

Kindly forward your resume to rizwan.rizvi@hauka.com

Regards,

Abeer Qureshi
Software Developer,
Software Research and Development.
Hauka Pvt. Ltd.

Job: Content Manager (Permanent - Lahore, Pakistan)

2005-05-25T21:26:00.000-07:00

We need a Content manager/ Data Entry Operator. The ideal Candidate should
have basic knowledge of

- Acrobat Reader
- Acrobat Writer
- Basic Adobe Photoshop

The person should be lahore resident.

Salary range is PKR. 6000 to 6000/month

SKILLS REQUIRED:
Adobe Photoshop

TO APPLY FOR THIS POSITION:Go to http://rozee.com.pk/job-details.php?cid=499&jid=1615#apply

COMPANY INFORMATION:
Sheraz Khan
Next Age Tech
530 Nizam Block. Allama Iqbal Town Lahore.
Lahore, Pakistan
http://www.nextagetech.com

Job: Content Writer (Permanent - Lahore, Pakistan)

2005-05-25T21:25:00.000-07:00

Our in-house creative team is looking for a fresh-thinking copywriter who’s great at generating brilliant concepts as well as writing all types of marketing copy, as defined by the creative team, for online advertising, web content. We need an enthusiastic self-starter and a true collaborator that thrives on converting business
strategies into effective marketing communications.

The candidate should be proficient at striking a fine balance between retail and strategic writing, articulate different voices with conciseness to capture different audiences, willing to take ownership of projects and drive them to fruition, able to work closely with the art director in coming up with a visually and verbally
compelling copy, and familiar with basic graphic issues.

Qualifications:

• Should have at least 1 year of copywriting and creative experience in an ad agency, marketing department, or freelance capacity
• Bachelor’s Degree in Computers,English, Advertising, Journalism, Marketing, or
other related areas of focus
• Superior writing ability and creative skills
• High-level problem-solving and analytical skills
• Ability to produce quality work within tight timelines
• Excellent communication and interpersonal skills

MA English , MA Literature will be preffered

If you are a team player, have a great attitude, an artistic eye and meet the
requirements above, please send a resume, cover letter, URLs of work that you have done to
aamir @ sofizar.com .Please include some writing samples (as doc files) and link to online portfolio. Those who will email only resumes without coverletters, writing samples and minimum salary expectations will not be considered .

SKILLS REQUIRED:
MS-Word

TO APPLY FOR THIS POSITION:Go to http://rozee.com.pk/job-details.php?cid=551&jid=1491#apply

COMPANY INFORMATION:
Zafar Khan
Sofizar
Q-Block Defence Housing Authority
Lahore, Pakistan
http://www.sofizar.com

Job: Creative Writer (Permanent - Lahore, Pakistan)

2005-05-25T21:23:00.000-07:00

Write corporate profiles, marketing material, slogans, web copy/text, articles and other text requirements. Coordinate with marketing staff and other company executives.

Salary range is PKR. 7,000 to 13,000/month

SKILLS REQUIRED:
MS-Word

TO APPLY FOR THIS POSITION: Go to http://rozee.com.pk/job-details.php?cid=360&jid=1269#apply

COMPANY INFORMATION:
Muhammad Bilal
Genex Business Solutions
108-M, Marghazar Colony, Multan Road
Lahore, Pakistan
http://www.genexbs.com

Terms Every Techncial Writer Must Know

2005-05-18T22:30:00.000-07:00

Authentication: The use of a password, certificate, personal identification number (PIN), or other information to validate an identity over a computer network.

Bookmark: A stored web page address (URL) that you can go to easily by clicking a bookmark icon in the Bookmarks Toolbar or choosing the bookmark's name from the Bookmarks menu.

Bookmarks Toolbar: The customizable toolbar that appears just below the Location Bar by default in Firefox. It contains buttons for your favorite bookmarks (or folders containing groups of bookmarks) that you can add or remove.

Cache: A collection of web page copies stored on your computer's hard disk or in its random-access memory (RAM). Firefox accumulates these copies as you browse the Web. When you click a link or type a URL to fetch a particular web page for which the cache already contains a copy, Firefox compares the cached copy to the original. If there have been no changes, Firefox uses the cached copy rather than refetching the original, saving processing and download time.

Certificate: The digital equivalent of an ID card. A certificate specifies the name of an individual, company, or other entity and certifies that a public key, which is included in the certificate, belongs to that entity. When you digitally sign a message or other data, the digital signature for that message is created with the aid of the private key that corresponds to the public key in your certificate.

Client: Software (such as an Internet browser) that sends requests to and receives information from a server, which is usually running on a different computer. A computer on which client software runs is also described as a client.

Cookie: A small bit of information stored on your computer by some web sites. When you visit such a site, the site asks Firefox to place one or more cookies on your hard disk. Later, when you return to the site, Firefox sends the site the cookies that belong to it. Cookies help web sites keep track of information about you, such as the contents of your shopping cart. You can set your cookies options to control how cookies are used and how much information you are willing to let web sites store on them.

Cookie Manager: The part of Firefox that you can use to control cookies.

Cryptography: The art and practice of scrambling (encrypting) and unscrambling (decrypting) information. For example, cryptographic techniques are used to scramble and unscramble information flowing between commercial web sites and Firefox.

Decryption: The process of unscrambling data that has been encrypted. See also encryption.

Digital ID: See certificate.

Encryption: The process of scrambling information in a way that disguises its meaning. For example, encrypted connections between computers make it very difficult for third-parties to unscramble, or decrypt, information flowing over the connection. Encrypted information can be decrypted only by someone who possesses the appropriate key.

Extensible Markup Language (XML): An open standard for describing data. Unlike HTML, XML allows the developer of a web page to define special tags. For more information, see the online W3C document Extensible Markup Language (XML).

Feed: An XML web page that contains a list of links to other web pages. Special programs can read feeds to create a list of headlines from the links, automatically updating the list as it changes. News web sites use feeds to quickly publish the latest headlines, and personal online journals often use feeds to quickly notify visitors about new entries. See also live bookmark.

File Transfer Protocol (FTP): A standard that allows users to transfer files from one computer to another over a network. You can use Firefox to fetch files using FTP.

FIPS PUBS 140-1: Federal Information Processing Standards Publications (FIPS PUBS) 140-1 is a US government standard for implementations of cryptographic modules — hardware or software that encrypts and decrypts data or performs other cryptographic operations (such as creating or verifying digital signatures). Many products sold to the US government must comply with one or more of the FIPS standards.

Helper Application: Any application that is used to open or view a file downloaded by Firefox. A plug-in is a special kind of helper application that installs itself into the Plugins directory of the main Firefox installation directory and can typically be opened within Firefox itself. Microsoft Word, Adobe Photoshop, and other external applications are considered helper applications but not plug-ins, because they don't install themselves into the browser directory but can be opened from the download dialog box.

Home Page: The page Firefox is set to display every time you launch it or when you click the Home button. Also used to refer to the main page for a web site from which you can explore the rest of the site.

Hypertext Markup Language (HTML): The document format used for web pages. The HTML standard defines tags, or codes, used to define the text layout, fonts, style, images, and other elements that make up a web page.

Internet: A worldwide network of millions of computers that communicate with each other using standard protocols such as TCP/IP. Originally developed for the US military in 1969, the Internet grew to include educational and research institutions and, in the late 1990s, millions of businesses, organizations, and individuals. Today the Internet is used for email, browsing the World Wide Web, instant messaging, mailing lists and usegroups, and many other purposes.

Internet Protocol Address (IP address): The address of a computer on a TCP/IP network. Every computer on the Internet has an IP address. Clients have either a permanent IP address or one that is dynamically assigned to them each time they connect with the network.

Java: A programming language developed by Sun Microsystems. A single Java program can run on many different kinds of computers, thus avoiding the need for programmers to create a separate version of each program for each kind of computer. After Java is installed, Firefox can automatically download and run Java programs (also called applets).

JavaScript: A scripting language commonly used to construct web pages. Programmers use JavaScript to make web pages more interactive; JavaScript is often used to dynamically validate forms and select buttons. JavaScript can be used with Java, but it is technically a separate language. Java is not required for JavaScript to work correctly.

Live Bookmark: A special type of bookmark that acts as a folder to contain the links in a feed. You can create a live bookmark by visiting a site with a feed, clicking on the live bookmark icon in the Status Bar, and selecting the feed format you wish to use.

Location Bar: The field (and associated buttons) near the top of a Firefox window where you can type a URL or search terms.

Master Password: A password used to protect saved passwords and other private data. Firefox will prompt you for your master password when you wish to access this data. If you have multiple security devices, each security device will require a separate master password.

Navigation Toolbar: The toolbar near the top of the Firefox window that includes the Back and Forward buttons.

Password Manager: The part of Firefox that can help you remember some or all of your names and passwords by storing them on your computer's hard disk and entering them for you automatically when you visit such sites.

PKCS #11: The public-key cryptography standard that governs security devices such as smart cards.

Plug-in: A type of helper application that adds new capabilities to Firefox, such as the ability to play audio or video clips. Unlike other kinds of helper applications, a plug-in application installs itself into the Plugins directory within the main Firefox installation directory and typically can be opened within Firefox itself (internally). For example, an audio plug-in lets you listen to audio files on a web page or in an e-mail message. Macromedia Flash Player and Java are both examples of plug-in applications.

Private Key: One of a pair of keys used in public-key cryptography. The private key is kept secret and is used to decrypt data that has been encrypted with the corresponding public key.

Proxy: An intermediary or "go-between" program that acts as both a server and a client for the purpose of making requests on behalf of other clients.

Search Engine: A web-based program that allows users to search for and retrieve specific information from the World Wide Web. The search engine may search the full text of web documents or a list of keywords; it may also use librarians who review web documents and index them manually for retrieval. Typically, the user types a word or phrase into a search box, and the search engine displays links to relevant web pages.

Secure Site: A site that uses encryption in connections with Firefox to prevent other malicious Internet users from viewing transmitted data. When you visit secure sites, Firefox displays a lock icon in the Status Bar and the Location Bar. Firefox also displays the site's domain name in the Status Bar (to prevent malicious sites from stealing your data) and turns the background of the Location Bar to yellow.; Some sites may consist of both secure and insecure data; the insecure data usually is non-private, although it isn't guaranteed to be so. For such sites Firefox will display a lock icon with a slash through it in the Status Bar and Location Bar and will not display the site's domain name in the Status Bar so that you know that the current web page isn't completely secure.

Secure Sockets Layer (SSL): A protocol that allows mutual authentication between a client and a serverfor the purpose of establishing an authenticated and encrypted connection. SSL runs above TCP/IP and below HTTP, LDAP, IMAP, NNTP, and other high-level network protocols. The new Internet Engineering Task Force (IETF) standard called Transport Layer Security (TLS) is based on SSL. See also authentication, encryption.

Server: Software (such as software that serves up web pages) that receives requests from and sends information to a client, which is usually running on a different computer. A computer on which server software runs is also described as a server.

Status Bar: The toolbar that appears at the bottom of any Firefox window. It shows status icons on the right.

TLS: See Secure Sockets Layer (SSL).

Transmission Control Protocol/Internet Protocol (TCP/IP): A Unix protocol used to connect computers running a variety of operating systems. TCP/IP is an essential Internet protocol and has become a global standard.

Uniform Resource Locator (URL): The standardized address that tells Firefox how to locate a file or other resource on the Web (for example, http://www.mozilla.org). Type URLs into Firefox's Location Bar to access web pages. URLs are also used in the links on web pages go to other web pages. Also known as an Internet or Web address.

Web Page: A single document on the World Wide Web that is specified by a unique address or URL. A web page may contain text, hyperlinks, and graphics.

Web Site: A group of related web pages linked by hyperlinks and managed by a single company, organization, or individual. A web site may include text, graphics, audio and video files, and links to other web sites.

World Wide Web: Also known as the Web. A portion of the Internet that is made up of web pages stored by web servers and displayed by clients called web browsers (such as Firefox).

Source: Mozilla Firefox Help

The Future of Robo Help

2005-05-12T22:15:00.000-07:00

During the opening segment of the WritersUA Conference for Software User Assistance, Joe Welinske, President of Writers stated that Macromedia has put RoboHelp on "sunset" and that RoboHelp will likely no longer be "in common use" within 2 years. To set the record straight, here is a detailed presentation of his information and conclusions about the current and future status of RoboHelp.

What did I say at the WritersUA Conference?

On March 21st, in Las Vegas, as part of the opening session of the WritersUA conference, a panel of pundits presented fifteen predictions about short and long term changes in the IT industry, the user assistance arena, and specific tools and technologies. One of my predictions was that "Two years from now, RoboHelp will no longer be in common use." By "common use," I meant that it would not be a Help authoring tool actively employed on a regular basis by most documentation departments in the software industry.

My prediction about RoboHelp was not simply a shot-in-the-dark statement done for entertainment purposes. Rather, it was based on numerous conversations that I had with current and former employees of Macromedia over the past six months. These employees were key players in the areas of marketing, administration, and software development. I gathered information from several prominent independent consultants. Observations about recent marketing moves are also part of the picture. Just recently, I had a telephone interview with Miriam Geller, Director of Product Management at Macromedia. My questions and her responses are included toward the end of this article.

Why do I think RoboHelp has been 'sunset'?

The crux of my prediction about RoboHelp is that the product has been informally sunset by Macromedia. The term "sunset" is used in the software industry to denote a gradual phasing out of development and support for a product. My various sources have confirmed that all development team members had either been discharged or resigned as of the first week of March of this year. By "development team," I am referring to the technical personnel who had been involved in creating new versions of the software and actively maintaining the existing code base.

Development cutbacks to the eHelp product line began right after the acquisition by Macromedia with the discontinuation of RoboPresenter, RoboLinker, and RoboPDF. This was followed by discontinuation of the RoboHelp for FrameMaker product and the termination of its product manager. Additional RoboHelp administrative and development staff were let go over the ensuing months, including CFO Anthony Olivier. At least two ex-RoboHelp developers have applied for jobs at other Help tool companies and have described the dismantling of the development staff. Through another source, I learned that there was a plan to export the maintenance of the RoboHelp code to India. This was confirmed by an ex-RoboHelp employee. More recently, the Macromedia internal deadline for moving the code maintenance to India had passed and a subsequent decision was made to discontinue that scenario entirely. 0

Many ex-Macromedia (eHelp) staff members were at the March WritersUA Conference as members of a new company called MadCap Software. Conversations with several of them confirmed, to varying extents, what had transpired with the RoboHelp product over the past months. The most recognizable face at MadCap Software (for much of the current RoboHelp user-base) is V.P. of Product Management Michael Hamilton. Mike was the last member of the RoboHelp development team to leave Macromedia. He resigned on March 7 from his post as RoboHelp Product Manager—a post he held for the past six years. Mike Hamilton discussed this situation in detail on a recent post to the TECHWR-L list.

In an interview with Chuck Martin at the WritersUA Conference, Mike noted that recent changes at Macromedia, such as the decision to no longer sell RoboHelp maintenance contracts, crystallized his feelings about resigning. The RoboHelp maintenance contracts that Mike referred to were a combination of support and new releases. The new releases aspect of the maintenance contracts has been killed and only the support component is now provided. Additionally, the Gold Support program has been eliminated for RoboHelp. Gold is the top tier of Macromedia Support. The key element that separates Gold from the less expensive support programs is access to Senior Level Product Support Engineers. On the global Macromedia Support page, RoboHelp is the only Macromedia product that does not offer Gold access to engineers as a support option. The RoboHelp Support page was revised on April 14 to note that the "Product Updates & Upgrades" component of support is no longer available.

On the marketing front, Macromedia cancelled their Exhibition appearance at the WritersUA Conference just three weeks before the event. My exhibition contact at Macromedia indicated that not a single person was available to staff the show. I was also told that there was nobody available to make any kind of statement to the attendees about the Macromedia absence. Our organization received a box of CDs and brochures to distribute at the conference in lieu of a personal presence by Macromedia representatives.

Macromedia is apparently also going to be absent from the upcoming annual conference of the Society for Technical Communication. They are not listed on the latest Exhibitor roster and a source has confirmed that they have cancelled their appearance. This gathering has been one of the main shows for the RoboHelp product team over the past ten years. The conference brings together over fifteen hundred technical writers, many of whom are either using the product or have an interest in it. Also, RoboHelp ended its long-standing Platinum sponsorship of the TECHWR-L web site in February.

What could make RoboHelp obsolete?

The actions described above lead to the conclusion that the future viability of RoboHelp is very much in doubt. Macromedia will likely keep the distribution center going, as well as some basic level of email support. The software will probably continue to be sold until revenues dip below a profitable threshold. However, a software product that is not evolving is shortening its lifespan. Eventually, IT industry developments will make a static RoboHelp obsolete. The most immediate threats are the upcoming releases of IE 7 and AOL/Netscape 8. Who will be available to fix the code if these browsers break the WebHelp component of RoboHelp? It is certainly possible that a new development team could be reconstituted in the future. However, the efficiency and effectiveness of new programmers digging into a decade of legacy code is very questionable. And if a new development team is the future solution, why would Macromedia eliminate all of the current experts in the first place?

Further down the road is the developer release of Windows "Longhorn" Help from Microsoft. This new Help system represents a significant leap forward in Help capabilities. Support for the Microsoft Help standard has long been a core source of revenue for RoboHelp. Any attempt to support Longhorn Help will require a considerable development effort, needing numerous programmers intimately familiar with the RoboHelp code. Another technology that will make the current version of RoboHelp obsolete is the continued growth of XML as the lingua franca of file formats. Making RoboHelp fully XML-compatible had been mentioned by RoboHelp developers as a key future feature.

I mentioned two years as a possible limit to RoboHelp's usefulness to most customers if active development has already ended. Depending on your particular needs, that could very well be extended by another year or two. According to Neil Perlin, an independent RoboHelp consultant and trainer, "external technical changes in the absence of a Robohelp upgrade will eventually make the product obsolete. Any changes in IE 7 that hurt WebHelp would clearly have an immediate impact; that's the biggest unknown." However, Perlin is more cautious about how soon other technologies would create a problem for RoboHelp. He predicts that "Longhorn will have an impact but, between the delay in its release and the required hardware and software upgrades, I don't see it having much impact before 2007. And as powerful as XML is, most people's XML and single sourcing needs today are met by X5's XML and single sourcing feature sets."

Didn't Macromedia buy eHelp for RoboHelp?

One of the aspects of this situation that makes it hard for people to believe is that RoboHelp has been and is today a very profitable product. As mentioned earlier, it has an enormous market share. It is also recognized as an extremely good product and it has won numerous awards. In the wake of the bursting of the Internet bubble, products with a positive cash flow are generally in short supply and tend to be valued highly. The assumption by many was that Macromedia recognized this, and that was the reason the company paid in the neighborhood of $65 million dollars for eHelp. Even for a company with projected 2006 revenues of $500 million, that's a lot of money. However, the wildcard is another product that came along in the eHelp sale—RoboDemo. Now renamed Captivate, this is an authoring tool that simplifies the development of Flash-based eLearning modules. An ex-eHelp officer told me that the top hierarchy of Macromedia had always been much more interested in RoboDemo than RoboHelp. RoboDemo/Captivate apparently fit very well into Macromedia's plans for its future product line, while RoboHelp did not.

What about people using RoboHelp today?

In my conference predictions, I was careful to remind the attendees that RoboHelp will remain the product that it is and people can continue to use it as is. If you have a version of X5, or an earlier version for that matter, it should continue to support your efforts well into the future. The capabilities of the currently shipping product are in no way diminished by the ending of active development. However, the impending mismatch with evolving technologies should and will be a concern for many documentation departments.

It would be prudent for all user assistance professionals to assess their needs and options. David Knopf, a specialist in online technologies notes, "For some time now, we've been recommending that our clients avoid starting new projects with RoboHelp and that existing RoboHelp shops plan for a future in which their workflow does not rely on RoboHelp. Macromedia's actions since acquiring eHelp strongly suggest that RoboHelp is now a dead end." William Meisheid of Sageline Publishing adds, "There are many ways to sunset products, some of which are user-friendly, many are not. This is not and with as large and loyal a user base as RoboHelp possessed, a bumbled shutdown will not endear Macromedia and their other product offerings to the RoboHelp user community and opinion makers."

It is likely that competing products will try and grab a share of the RoboHelp market. At the WritersUA Conference, ComponentOne Doc-to-Help announced the addition of a RoboHelp conversion feature. Other vendors have expressed an interest in doing something similar. It will not be a simple process to migrate a complete and robust RoboHelp project to another product and conversion tools will be necessary. Another issue is that currently no product clearly offers the same working paradigm and feature set as RoboHelp. Major competing tools present a markedly different approach to Help authoring. Either the competing tools will adjust, or retraining will be required.

A number of RoboHelp users with maintenance contracts have already expressed concern about what this all means for them. A few have mentioned that their support plans guaranteed at least one new release per year. I am not personally familiar with the details of what is and is not promised.

The story isn't finished

Subsequent to my comments at the WritersUA Conference, Miriam Geller, Director of Product Management at Macromedia, posted a note on the RoboHelp General Discussion Forum. It would be best for you to read it yourself and make your own assessments about what it means. It does not appear to invalidate any of the statements or assumptions in this article.

On April 13, I conducted a telephone interview with Miriam Geller. I began the discussion by asking her if she could confirm that an active RoboHelp development staff was no longer in place. Her reply was, "Macromedia takes an overall look at a team and makes adjustments. I can't comment on specifics." I asked how many developers are currently working on RoboHelp upgrades and maintenance as their primary responsibility. Geller replied. "There are people in the company who are knowledgeable about RoboHelp." I asked Geller who, if anyone, was acting as RoboHelp Product Manager in place of Mike Hamilton. She said she was personally fielding questions from outside Macromedia and sending them to the appropriate people. Regarding the moving of code maintenance to India, Geller had no comment other than to confirm that Macromedia has a facility there.

I asked about general development priorities and also about the impact of IE 7 and Longhorn Help. Her replies were "We don't talk about future releases."; "Macromedia has longer product release cycles than eHelp had."; "Macromedia has a big suite of products. What we're working on one day may not be a priority the next."

I mentioned that the canceling of conference appearances and sponsorships was fostering some unease about the level of commitment to the user assistance community. Geller said, "This is a repercussion of a product in the hands of another company. We're very targeted about the shows we attend. Decisions that eHelp made about which marketing efforts to support are not necessarily going to be shared by Macromedia. We make decisions to spend marketing dollars with best reach."

I asked how the termination of RoboHelp maintenance contracts was going to affect those who hold them and believe they are due a product update. Her reply was, "If they have a question, they should call customer support. Different maintenance plans have different longevity. If they don?t feel like they are getting an answer, they should escalate to me." Geller added that, "Macromedia is evaluating support for its products across the board." It is important to note that Captivate, with a small fraction of RoboHelp sales, currently offers Gold support (engineer access) and RoboHelp does not.

I asked why RoboHelp for FrameMaker had been discontinued. Geller said, "There is a long list of acquired companies where the products went away. The FrameMaker edition was a brand new product, unlike the original RoboHelp." She also noted that RoboHelp and Captivate were the key products in the acquisition, but would not provide more details about the acquisition strategies.

The acquisition of Macromedia by Adobe is now another element in this story. Possibly the Adobe executives might see a value in RoboHelp that the Macromedia folks did not. However, it appears that the RoboHelp advocates in Macromedia are all gone. Also, a small division like RoboHelp that was ignored by a $500 million dollar revenue company is going to seem even more insignificant in a company with income of $1.7 billion. In the short term, it is not likely that this will result in any positive movement toward a RoboHelp upgrade.

Final thoughts

This article and my prediction about the future of RoboHelp are not meant to be an attack in any way. RoboHelp is an important tool to thousands of developers throughout the world and they deserve to have as much information about the future of the product as possible. Our WritersUA constituency consists of about 10,000 user assistance professionals of whom an estimated two-thirds use RoboHelp. My own history with RoboHelp goes back at least thirteen years. I still have my version 1.0 of the product on a 5-1/4" floppy. From around 1992 to 1998, I actively used RoboHelp in contracting projects for a variety of software development clients. I was also one of the first people to conduct RoboHelp training classes. I designed my own RoboHelp training materials and traveled around the country doing RoboHelp seminars until around 1998. RoboHelp techniques continue to be a popular topic at conferences.

Making the prediction about the possible demise of RoboHelp at the WritersUA Conference was very difficult for me. To a large extent, RoboHelp was responsible for helping technical writers become accepted as members of the software development community. It was a tool that empowered us to create our own piece of the software puzzle without help from programmers. In the years before HTML, this was not a trivial issue. While the eHelp face of RoboHelp was often decried because of its overly aggressive marketing tactics, from a technical standpoint, the product was always at least very good, very often it was great. RoboHelp was frequently evolving, often pushing the envelope, and always attempting to predict what customers would like in the future. If it fades way, RoboHelp will be missed.

This will be an ongoing story. If you would like to make any contributions/corrections to this article, please send me an email or give me a call at 206-285-2605. However, I may not be able to respond to queries requesting additional details or opinions.

http://www.winwriters.com/articles/rh/index.html

Here is Macromedia's response to this prediction.

Writing a Datasheet

2005-05-06T06:05:00.000-07:00

Overview

The datasheet should be the perfect summary piece for your product. It should provide enough information to intrigue the reader enough to have them either want to evaluate your product or obtain more detailed information.

The datasheet is designed to be a listing of facts and figures. It should be presented with a factual tone and contain hard data. You do not want the datasheet to be a display of creative writing.

Datasheets are now so standardized for the computer industry that people have come to expect a given layout and the specific information listed below in the datasheet. Deviation from this standard format means that the reader may have a hard time finding the information they need. If they are looking at your datasheet next to your competitors then they might eliminate your product before even looking at it.

Target Audience

Understanding your target audience is imperative before writing a datasheet. If your audience is highly technical, they will not want to be bothered with a lot of words about the benefits of the product. They understand the technology and are looking for specific features. If your audience is less technical you will need to help them make the connection between a feature and what it will do for them.

Outline

The following is an example datasheet outline:
- Description – Many people spend so much time entrenched in their product that they forget
that other people don’t automatically know their product. It is important to start the brochure or
datasheet with a very concise description in order to put the features and benefits
in context. If you have multiple products in your product line, make sure that each datasheet
quickly differentiates each product from rest.

- Visual Element -- A picture, screen shot, or a diagram that shows either the components of
the product or how the product fits in its environment should be on the front page.

- Key benefits – A statement of the key benefits of the product. Three bullet points are ideal. If
this is a technical audience list the three key features and their benefits.

- Features and benefits and/or specifications – On the back should be a listing of features and
benefits if it is a software package. If the product is hardware then specifications should be
included. When writing up features and benefits keep your competitors in mind. Since your
audience will probably be looking at your product alongside the competition, you will want to
highlight the features that set your product apart from its top tier of competitors.

- Requirements – List the software and hardware that is required to support your product.

- Contact information – Have all your contact information at the bottom of the datasheet. Include
all copyright and trademark information. I have noticed that Microsoft now puts some legalese at
the end of their datasheets that says, “This datasheet is for informational purposes only.
MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS SUMMARY. Companies, names
and/or data used in screens and sample output are fictitious, unless otherwise noted.” Though
this may be a little drastic, you may want to check with your legal department to see if there are
any disclaimers needed.

Layout

Datasheets are one page with information on both the front and the back. The front contains the description, key benefits, and a picture. The back has more detailed features and benefits, specifications, requirements, and contact information.

If you have multiple products in your product line, make sure that the layout of each datasheet is similar to give the appearance of a family. You will probably want turn your datasheet over to an artist for final layout and design work.

Process

Here is a basic process for writing datasheets:
- Identify the target audience of the datasheet.
- Gather features and benefits from your own use of the product, beta customer use,
engineering, and other internal resources.
- Boil down the benefits to the most important three for your product.
- Decide on the picture.
- Assemble and write datasheet.
- Review with internal resources.
- Provide raw materials to an artist for layout.
- Review every draft that comes back, especially blue lines. Have a second person review the
blue line. It is easy to miss the same error several times. A fresh set of eyes is always helpful.

The Basics

Because it is now so easy to write a datasheet and print it on a laser printer, many people are writing and handing out datasheets without going through a formal printing process. The downside of this is that the datasheet is often not reviewed by a professional writer and the layout is not designed by a professional designer. Under these circumstances, I feel obligated to add a section on the very basics of grammar and design. The following are some key points to remember:

- Use bullets whenever possible to list features or benefits
- Create bullets with consistent structure -- if your first bullet starts with a verb, then all bullets
should start with a verb
- Keep text to a minimum -- remember that this is a summary. Create technical white papers
for backup if necessary
- Use a serif font (a font with those little lines at the top and bottom) for the body of the
datasheet. It is easier for the eye to read blocks of text with a serif font

If you don't have any training in design and you need to do a layout yourself, it is worthwhile to read Robin Williams wonderful book Non-Designer's Design Book .

http://infrasystems.com/writing-a-datasheet.html

Did you know?

2005-04-14T22:55:00.000-07:00

Joseph D. Chapline was the first technical writer to introduce software documentation to the rest of the world. Back in the year 1940, he worked for Eckert and Mauchley and was the first technical writer employed to document the way an operating system worked. The first user guide he wrote was Binac Computer User Guide.

Sun Microsystems' Java programming language was first used in a device that brewed coffee.

This is the first ever blog on technical writing in Pakistan.

Creating Prototypes

2005-04-11T00:52:00.000-07:00

After you've prepared your document outline, it's time to develop the document prototype.

Why create prototypes? There are three main reasons for creating prototypes:

1 - It helps test the page layout, design, headings etc. Also, if you need to revise the document structure, you can identify it early in the process by prototyping.
2 - You can show users, colleagues and Senior Management the prototype and ensure that the manual meets their needs. This step also helps to get management 'buy-in' and sign-off.
3 - It's easier to start writing, as the prototype serves as a document blueprint.

Tips for creating prototypes? When you preparing the prototype, keep in mind the following:

Use the active voice: This makes the writing easier to follow. With the active voice, the subject of the sentence performs the action of the verb. For example, "You can visit the page by clicking this link." The passive voice often takes more words than the active voice and can create ambiguity.

Use the term "you" for the user: When you do this, the documentation seems more friendly and approachable.

Write your steps as numbered lists: Indent the numbered lists to make them stand out from the rest of the text.

Use command verbs: When writing steps, ensure that they follow the correct sequence.

Choose words carefully: Define new terms in a glossary. Use simple words whenever possible. Avoid technical terms and jargon that are not required.

Be concise: Use the least possible words to explain concepts, especially when writing steps in processes and procedures.

Be consistent: When you use a specific term to refer to a function, continue to use it throughout the publication. Don’t change the terms for the sake of variety. This will only confuse the user!

Highlight critical information: Use bold type for warnings and critical information, or place a symbol next to the text for emphasis.

If you use tables or screenshots, include them in the prototype. Your reviewers will then have a more reliable document sample.

http://www.klariti.com/technical-writing/Creating-prototypes.shtml

Approaches to Version Control Software

2005-04-11T00:49:00.000-07:00

Many documentation departments face the challenge of managing hundreds of files with many writers working on them at the same time. For a Documentation Manager, there are several options available to remedy this; most involve either Microsoft SourceSafe, CVS or PVCS to manage this thorny process.

Lack of Guidelines: When it comes to version control procedures, the lack of formal guidelines is a serious issue for Publication departments; For example, there may be no "best practice" guidelines for "getting" versus "checking out" documents.
With certain software packages you can "get" a copy of a file in read-only mode and then make it write-able. This overrides the security "check out" feature of the system which can later prove counter-productive and create even more confusion.

Checking Out: Checkout procedures have several purposes: 1. They put a copy of the file on a local machine. 2. They lock the file; only the user who checked it out can check it back in. This process protects your team from itself — it alerts the rest of the team when someone is working on that file. Version control software protects team members when two or more writers attempt to update a document simultaneously. Should this happen, they risk losing one writer's contribution, as the last saved version will overwrite the previous version.

Using CVS: CVS doesn't truly support a lock system. Instead, its default mode is a 'merging model'. You can use a lock system with CVS if you use the -L and -l options to the Admin command.Multiple users can check out the same documents and then attempt to check them back in. When working in ASCII modes, such as HTML, this works fine as it will calculate your differences from the last version and apply them. Depending on your product version and platform, it can figure this out quite well.

However, if there is a conflict it will stop you checking files back in, and force you to manually reconcile the difference.

RCS and Microsoft SourceSafe offer locking.

Note: You can override the checkout lock, but use this in emergency situations only, e.g. when someone leaves the company and forgets to unlock their files.

When you override a lock, ensure that the locker has checked in the most recent version, or you'll lose the work.

Managing versions by product line:

When preparing documentation plans, one approach is to delineate your documents based on product lines and give each writer their own set of files to manage. You then have to ensure that there are no files shared between products.If you don't control this, you will end up with writers working on the same files, and everyone having copies of the files on their local drives to edit. Documents will clash when they are checked back in.Needless to say, the larger the team, the more important a clearly defined source control procedure is followed.

http://www.klariti.com/technical-writing/Version-Control-Software.shtml

Improving Appearance of Technical Document

2005-04-01T05:18:00.000-08:00

Everyone would prefer reading a technical document that is visually appealing rather than one that is cluttered with dense copy and little or no white space. Simply put, white space is blank space on the paper. It can be used for various techniques as well as an easy way to enhance your document's appearance.

- White space can be used to achieve the following results:
- Frame the content
- Separate ideas
- Define sections of your document
- Provide relief from copy
- Highlight information

White space simultaneously "opens up" the document and segregates information into manageable segments. Your readers can only digest so much information at one time. Think of white space as you would a five-course meal served in a four-star restaurant. Served in distinct courses, the food's visual impact is much greater than that of a crowded buffet table, which is laden with as much food as possible in as little space as possible.

You can achieve white space in the following ways:

- Before and after headings
- Wide margins on all four sides
- The space between columns of words or numbers
- Unjustified right margins
- Indented sentences
- Between paragraphs
- Bulleted items in a list

You may already be incorporating these techniques in your technical documents; however, if you are not, experiment with the ones you are not currently using. To see the difference between a document that appears crowded and dense with text and one that is open and visually appealing, compare a document that you have already written with the same document after you have enhanced it with white space. The difference will astound you-and please your readers.

Using Emphasis Techniques

You can use four different techniques to emphasize material in technical documents. The four most commonly used are the following:

- Typographical
- Graphical
- Spatial
- Verbal cues

Typographical

The following typographical techniques are easy to incorporate into a technical document:

- Bolding
- Italicizing
- Underlining
- USING ALL CAPITAL LETTERS
- {Putting words in brackets}
- "Using quotation marks"

Bolding is an effective way to separate headings from the text of a document. When used sparingly, bolding can be a dramatic method of highlighting important information.

In the same way, italicizing can draw your reader's eye toward words that need special notation. Technical writers use italics to differentiate subheadings from headings, to distinguish technical words and phrases that will be defined later, and to set apart material that is quoted from another source.

Underlining is used sparingly because it is often hard to distinguish letters that have descenders when underlined. For example, words that contain the following letters run the risk of being obscured: j, p, q, y. Note these same letter when they are underlined: j, p, q, y.
Using all capital letters works well for short headings and words that need special emphasis; however, studies have shown that text using all capital letters is much harder to read than what is called "mixed case." Compare the following two headings:

USING GRAPHICS IN TECHNICAL DOCUMENTS
Using Graphics in Technical Documents

Brackets are an effective way to separate parenthetical text; however, bracketed information appears to be an afterthought. If it is important, it should be given equal status to the information that precedes or follows it. Often, the busy reader will skip information that is bracketed, assuming that it is an afterthought or secondary in nature.

Quotation marks have been almost entirely replaced by italics. However, when you wish to give special meaning to a word or phrase, quotation marks will highlight the words. Also, a direct quote may appear within quoted information. In that instance, quotation marks indicate that a person or source is being quoted verbatim.

Graphical Techniques

Graphical techniques include framing, shading, and coloring. These techniques often do not reproduce well when multiple copies are made. Shades of gray can easily become too dark to read or too light to be effective. In a technical report, a chart may be framed, shaded, or colored to make it stand out from the regular text. Using colors for pie charts and bar graphs is especially effective. Unfortunately, the cost of color is often prohibitive. If the document is written for in-house distribution, the variations of gray can separate bars or slices of the pie. Again, it is important to determine if the shadings reproduce well.

Spatial Techniques

Spatial techniques include the use of white space and consistent placement of information. An example of this would be to always place the name of the procedure at the top of the page, the page number centered at the bottom of the page, headings centered, and subheadings flush left. By being consistent with such information, your reader knows exactly where to look for what they need.

Verbal Techniques

Verbal techniques include using the same words as identifying terms such as Important, NOTE, or Caution! When you write procedures, certain words tell the users what conditions must be met before they can go on to the next step. Words such as NOT are much more recognizable than words that start with a negative prefix such as in or un.

Compare the following two conditional statements:

If water levels are NOT adequate,Then adjust the flow valve.
If water levels are inadequate,Then adjust the flow valve.

Technicians are trained to focus on verbal techniques such as NOT. Recognizing what to do-or in this case, what not to do-in the field can literally mean the difference between a safe working environment and one that is potentially fatal.

Technical documents are technical in nature. They lack the sexy, "cool" appearance of a glossy magazine or a best-selling novel. Even so, there is no reason why a technical document has to be cluttered, dense with copy, and uninteresting. By considering the appearance of your document and using visual enhancements, your work may stand out as the model of what all other documents should look like in your company or your field. You may not have begun your technical career with dreams of writing technical documents, but as your work is continually praised and held as a standard, you will feel a great sense of accomplishment.

Catherine S. Hibbard, http://www.salesvantage.com/article/view.php?w=77

Writing for International Audience

2005-04-01T03:56:00.000-08:00

Ideally, software and its documentation will be localised (translated) into the languages used in the target markets. However, in many cases, it's not cost-effective do this. Even if the target markets are the English-speaking countries, there are differences between the way English is used in the USA, Britain and Australia for example, and it's easy to cause confusion. This article examines a few issues.

Most readers will have no problem whether they see "dialog box" or "dialogue box" (assuming that they know what one is in the first place!). However, is "12/1/1999" the 12th January or 1st December? If your software is for an international market, then it makes sense to avoid ambiguities caused by differences in language usage.

Then consider readers who are not native English speakers. Many verbs in English consist of two or three words. Often, they can be separated by a noun. These phrasal and prepositional verbs (which typically are of Anglo-Saxon origin) can sometimes be a problem for people whose first language is not English; equivalent verbs which are often derived from Latin and Greek roots are often more easily understood. Here are a few examples of problematic verbs and their alternatives:

Don't use: bring up (a menu)
Use: obtain

Dont' use: end up with (a result)
Use: results in

Don't Use: fill out (a form)
Use: complete

Don't Use: put off (a decision)
Use:delay

Don't Use: turn up (the volume)
Use: increase

There is a counter-argument that says non-technical users (who are native English speakers) may feel more comfortable with words of Anglo-Saxon origin, because they are the words of everyday speech.

Finally (and not seriously!), if users break their keyboards after you've instructed them to "hit the Enter key" when you mean "press", who is to blame?

http://www.techscribe.co.uk/techw/international_english.htm

An Alternative to Microsoft Word

2005-03-21T23:05:00.000-08:00

Why consider OpenOffice.org at all? Ignoring the functionality and features for a moment, there are several practical reasons:

- OpenOffice.org is available in over twenty-four languages, and projects for additional languages are announced regularly. In addition, the program runs on the Windows, Linux, and Solaris operating systems. The Mac OS X version now has working pre-releases. This interoperability is far beyond that of most alternatives to MS Word.

- OpenOffice.org is released under the Lesser GNU General Public License. As open source software, it's free for the download from www.openoffice.org.

- Because OpenOffice.org is open source, you can legally install it on as many computers as you want. You can also reinstall it without contacting the project first. Neither is possible with MS Office.

- Because OpenOffice.org is open source, upgrades are also free. You can wait for official releases or upgrade to development releases as they become available, whichever you prefer. You can also choose between the latest official release and a developer's build, which may be less stable, but has the latest features that are being developed.

- Free support is available on the mailing lists. This support is as detailed and as accurate as any you can get from paid technical support. As often as not, you may be answered by a person who helped to write the code for the feature you're asking about.

- You or your company can join the OpenOffice.org project and influence the direction of future development.

- If your company needs a feature that isn't there, your company can sponsor development of the feature. The only restriction is that the finished feature will be available to everyone.

- If your company prefers a traditional relation with a software developer, your company can purchase StarOffice from Sun Microsystems for $75.95 for a single copy, or $50 per copy for 150. StarOffice is an enhanced version of OpenOffice.org, with additional translation filters, fonts and clipart, a manual, and a database (see www.sun.com/software/staroffice/6.0/index.html).
These reasons are obviously compelling to a great many. In the first month after OpenOffice.org was released, the project reported nearly a million downloads. Nobody knows exactly how many copies are circulating now, but a conservative estimate would be that there are at least ten million users in the spring of 2003. Judging from the number of reviews and their tones, the demand for StarOffice is almost as great.
...

Even more importantly, in several cases, OOo Writer has workable versions of features that have been crippled for several releases in MS Word.
Consider, for example, the following improvements over MS Word:

- True text frames, instead of text boxes. What's more, styles can be defined for frames. The last time MS Word tried to implement frames, styles couldn't be used inside them.

- The Navigator, a floating palette for moving around a document, not only by page, but by any object from tables to OLE objects and Notes. As a bonus, the Navigator can also be used for a quick outline view of headings. The Navigator is in addition to the Find and Replace tool. On large screens, it can be kept open in one corner for use.
...

In fact, if OpenOffice.org continues to be as much in demand as it was in the first month of its release, don't be surprised if you find features that originated in OOo Writer appearing in MS Word. Flaws and all, OpenOffice.org is looking more and more like a milestone in software.
Your word processing may never be the same again.

By: Bruce Byfield http://www.techwr-l.com/techwhirl/magazine/technical/openofficewriter.html

Why technical writers should learn XML now

2005-03-09T21:33:00.000-08:00

Lately you may have noticed the increase in newsletter articles, seminars, and monthly meeting topics that relate to XML. If you haven’t been keeping up, you might be wondering what’s all the fuss about XML? Or, why do I need to learn this if my job doesn’t have anything to do with XML? If you haven’t kept up, you might be interested to know why you should.

What is XML?

Early in its life cycle, XML was seen by some as an excellent technology for technical writers. “At this point, all signs indicate that XML offers the potential of being an ideal tool for tech writers to learn and use. In fact, tech writers are ideal candidates for using this technology because we already have the information development, design, and presentation skills necessary to develop these structured document formats”, (Deborah S. Ray, TECHWR-L, 1998)

Extensible Markup Language (XML), as the name implies, is a markup language that was designed to be an alternative to HTML as the language used to manage content on the World Wide Web. Unlike HTML, it enables the writer to create customizable tags, or labels, if you will, that make sense for use with the writer’s content. This feature allows the writer to create a document or system that is content-based or designed around the content, rather than a document or system that is designed around the limitations of HTML’s inflexible tags. Currently, technical writers use XML predominantly as a way to create content in one file format that can be reused for different purposes and transferred to many formats such as printed manuals or Web pages. Although it was originally designed for use as an alternative to HTML on the Web, its flexibility has driven its application to other uses such as Web Services, WebDAV, transferring data from one system to another, or ensuring that data exchange between systems is valid.

Why should technical writers learn it?

The proliferation of various applications of XML has increased dramatically in the last few years, not the least of which is Content Management (CM). Demand for CM services will increase significantly in the next few years. According to theWhir.com, “…content management services represent an attractive growth segment for the IT services industry…IDC’s five-year forecast anticipates that worldwide content management services spending will increase to more than $7.5 billion in 2007, with a compound annual growth rate of 12.8 %…A huge installation, customization, and training opportunity will occur during the forecast period as a new content infrastructure emerges.” (theWHIR's Web Host News, 2003) Installation, customization, and training all sound like areas with potential job opportunities for technical writers and communicators. And guess what technology is compatible with many of the CM programs on the market today, and expected to be an integral part of the growth and evolution of CM? XML. Speaking on CM at the November 17 STC meeting, Ann Rockley predicted we would see more of XML in the next two years.

If futuristic projections aren’t good enough reasons to learn XML, some of the more practical and “here and now” reasons may be. Although there are a variety of reasons to use XML that are beyond the scope of this article, some of those most common to technical writers are included.

Reusability of content may be the single biggest reason to learn and use XML. Whether you will be plugging it into specific CM software or a less formal system of managing content, once created, the same content can be used repeatedly for different purposes and in different output formats such as Web pages, handheld devices, PDF documents, online manuals, or printed materials. This feature of XML also lends itself nicely for use in a single-source system.

Customization is another reason to use XML. Creating customizable tags and structure for your content allows you to create a system that will meet very specific needs for you or your customers. At the very least, learning about the various components of XML such as tags, elements, and attributes will give you the ability to participate (politics aside) with other team members during the planning stages of the next content management, or other, system that will affect you. Increasing your ability to communicate with developers and other SMEs is an added benefit.

Receiving a significantly higher salary can result from having XML skills. According to online-learning.com, technical writers with XML skills “can add an extra $19K!” to their salaries (online-learning.com, 2000.) The skill set that will be expected with this higher salary may include the ability to develop XML documents, understand and work with DTDs and schemas, and create and work with style sheets that interact with the XML documents. If you’re ready for the challenge and growth of learning a new technology, you can expect a higher salary after gaining skills and experience in XML.

While XML was originally created as an alternative or supplement to HTML on the Web, its use and application has grown dramatically. Content Management is an area where the application of XML is expected to grow in the next few years, which will create many opportunities for all kinds of technical communicators. Other reasons to learn and use XML include reusability, customizability, and increasing your salary, not to mention the growth and challenge that go with learning a new technology. Currently, technical writers mainly use it as an efficient way of repurposing the same content to a variety of output formats. XML’s independence of proprietary platforms and formats and its ever-increasing application in the workplace means that its use will continue to grow, with it the likelihood and frequency that you will interact with it to some degree. It sounds like it’s time to start learning XML.

Renee Schurtz, http://www.stc-psc.org

Which HAT (Help Authoring Tool) should I buy?

2005-03-08T20:44:00.000-08:00

There are many Help Authoring Tools available and it be can be difficult to know which of them to use. Below you will find a summary of each tool, based on information from the vendors. They are all excellent tools, each with particular strengths.

RoboHelp X5

RoboHelp X5 is the latest version of Macromedia's Help-authoring software. New features include XML import/export, PDF import/export, content management, team-based authoring and support for JavaHelp 2.0. Compatibility for Word 2003 will be available in a service release for RoboHelp X5.

RoboHelp X5 can import existing XML content as well as export help content as XML. The software also supports the import and export of PDF content. The intelligent PDF import process renders PDF documents into their basic elements, such as text, images, and tables, each of which is independently editable after import for use in online Help. After a Help system has been created, it can be exported in print-ready PDF format.

RoboHelp X5's new content management features allow users to track what edits were made, when they were made, and by whom. At any time, any content can be rolled back to any moment in its history. The benefits of content management are increased when coupled with RoboHelp X5's new multi-author support, which features document check-in/check-out, document version comparison tools and support for remote authors.

XDK Professional

XDK Professional uses XML to gives you a great degree of control over how your online documents will look. It works as an integrated dynamic pane within Word, so you get all of Word's functionality. XDK can create multiple editions using different technologies and designs from one-source.

XDK's Table Of Contents technology automatically integrates into your online document to provide your readers with a hierarchical navigation tree. XDK also provides "topic Auto syncronisation and side entry". This means that as the user click on links and jumps around the document, the Table Of Contents will instantly update to show them where they are. XDK also makes context-sensitive links into standard HTML possible, because its technology allows direct entry into any point of your online document without causing errors with the Table Of Contents. XDK also has a powerful Dynamic Merging feature that will automatically aggregate multiple online documents. To the end user, the document appears as one seamless document, but as the author, you can break the project down into smaller chapters.

XDK Professional Service Pack 4 includes the following enhancements:

- New JavaHelp Compiler
- New Plain-HTML Table of Contents Compiler
- Improved import of HDK v3.1 through v3.4 projects

AuthorIT

AuthorIT is a single source documentation tool. Using AuthorIT, you can write information once, make changes in one place and maintain consistency. You can then use information in as many places as you want. It's the tool we use to produce this Web site.

Authors create pieces of re-usable pieces of information which are managed and maintained in a database and then published to many audiences, documents, and formats - both print and online. AuthorIT is a collaborative authoring tool where authors and other contributors work together as a team. It provides a multi-user environment with dynamic check-in and check-out, security control, standards control, version control, document release control, and integrated project and task management. You can also work offline - this means is you can work on your AuthorIT library outside the office when required.

Version 4.1 offers:

- A new rules-driven importer for bringing existing content into your project.
- A better editing environment. Tables, in particular, have been vastly improved.
- A new Generation module for creating the documents. As a result, generation
is faster.
- XML import and export
- Reduced localisation overhead of approximately 30%

WebWorks

WebWorks Publisher Professional enables you to quickly and easily convert FrameMaker documents into online delivery formats such as XML, XHTML and HTML. WebWorks Publisher WordHelp is the newest addition to the WebWorks product family. It offers single-sourcing to writers who use MS Word to develop content for online help.

WebWorks Publisher Professional 2003 offers new automated capabilities:
- New push-button deployment wizard
- Improved migration wizard
- Context-sensitive help designer
- New mapping interface
- Automatic TOC and index generation
- Automatic scaling and mapping of graphics

There are also new templates for Palm Reader, Fully 508 compliant WebWorks Help, Oracle Help, Dynamic HTML, HTML Help, and Microsoft Reader.

Epic

Epic is a suite of XML authoring tools for organisations that has large teams of authors, each working with large amounts of material that needs to be delivered to multiple audiences and disseminated in multiple forms.

The authoring software (Epic Editor) provides the following features:
- It provides a familiar word processing interface with support for change tracking, real-time spell
checking, multiple levels of undo, cut and paste, drag-and-drop editing, split screen views, multiple
windows and intuitive toolbars. Profiling helps authors create content that can be automatically
customized to specific audiences.
- It provides viewing, navigation and editing functions that are specific to structure.
- It can apply a stylesheet that gives the content a print or Web appearance.
- It lets authors insert only the tags that are valid at the current cursor position
(and it allows authors to see or hide tags).

Arbortext offers separate products for content conversion and publishing. The Enterprise E-Content Engine (E3) converts content to reusable XML components from Microsoft Word, Adobe FrameMaker and Interleaf. It will accept valid XML content from any source. E3 publishes dynamic content to print/PDF and Web/wireless. To publish to CD-ROM, Arbortext offers the CD-ROM Composer.

http://cherryleaf.com

What to Include in a Portfolio

2005-03-04T01:07:00.000-08:00

You have started to save your money to buy what is necessary to put your portfolio together, and now you want to decide what to include in it.

How to Get Started

- Start a "portfolio collection file": this file can literally be a file folder where you will put copies or originals of your work that you think you might want to include in your portfolio, or you can have a box that you fill with work. Basically, you can use whatever you want to use to hold your possible pieces.

The point is to start a collection of work. This collection doesn't have to be the definitive pieces you decide to use, but merely a collection of pieces you like, at this point.

- Keep in mind that this work doesn't have to be limited to school assignments: you can collect work from past job experiences or an internships. Plus, no one says you can't make a hypothetical brochure to show your skills with a certain software application, and that is also a good way to show off your design skills. Also, if you see a flyer that you think needs a redesign, then redesign it and put it in your portfolio along with a rationale of why you redesigned it, or be prepared to discuss this rationale with an interviewer.

When it comes time for you to fish through all of your work for your portfolio, choose only your best work. Be sure to save multiple copies of your work. You will need to replace wrinkled pieces as you begin showing your portfolio during several interviews.

Typical Pieces to Include

You should have an introduction page. Include your name, address, and/or any other information you want to include

>Resume and/or a vitae
>Giveaways
>Examples of your best work
>Entry cards
>Section dividers

Entry Cards

Basically, an entry card is an introduction to a piece that is included in your portfolio. Suggested components of the entry card can be as follows:

Entry Card Component

Title: Visual C++ -- Program I

Description: The first program introduces comments, assignment statements, input and output streams, #include, int main(), literal text strings, variable declarations, if-then-else statements, and arithmetic expressions. It also introduces the notion of a fuzzy set.

Course: Computer Science 1462: Fundamentals of Computer Science I

Instructor: Dr. Bob Jones

Date Completed: 4 March 1998

Objectives: 1. Comprehend a problem specification and design a solution to the problem
2. Create, debug, and submit a C++ program that implements a design
3. Use elementary C++ statements (assignment, I/O, if-then-else)
4. Create a program that takes as input from the keyboard four real numbers
which define a trapezoidal membership function of a fuzzy set.
The program must also take as input a fifth real number, x, and output to the screen
a message indicating the degree of membership of x in the fuzzy set.

Note: The assignment is on the first page of this section. The second page contains a listing of grading criteria. Following that information is my top-down design and my code.

This particular entry card was printed directly onto a cardstock section divider. You can adjust the entry card components to suit your needs, and you do not have to print the information onto section dividers. The point of these cards is to provide adequate background of the piece in order to introduce it and give the interviewer a context for the piece.

Suggested Pieces to Include

>Hardcopy (print) or online design or layout projects
>Brochures or flyers
>Marked up editing pages
>Reports
>Articles
>Programs
>Teaching or training materials
>Surveys
>Graphics
>Awards
>Redesigns

General Tips

If a piece is especially long, you might consider including only a sample of the long piece. You can bind the long piece and insert it into a side pocket, just in case the interviewer wants to peruse the full piece, but samples are usually fine for interview purposes. An example of this is a usability report. The report itself is quite long, but if you pull the first portion of the report to include in your portfolio, that will be enough to show the purpose of the report and the conceptual framework of the piece.

You should include some pieces you can "give away." If there is a piece that shows your best editing, you might make additional copies of that to give to the interviewer. Or, if you designed a Web site that illustrates your use of graphical design and firm grasp of online design and navigational strategies, don't hesitate to put that work on a disk and give it away during the interview. It is helpful if you print out a few pages of that disk copy to show the interviewer what is on the disk. An added touch is to design your own disk labels. For the technical writer whose expertise is in the multimedia production realm of the field, especially instructional design, don't hesitate to burn a few extra CD-ROMs of your work and give those to the interviewer. Again, designing your own label for your CD-ROM pieces is a nice added touch.

You should include a sheet-protected copy of your resume and list of references, and you should always have give-away copies of those in your portfolio. Plus, sheet protected copies of your transcript(s) are recommended, as well as a few giveaway copies. While the transcript is a not an overwhelming popular giveaway request, it is requested, nonetheless. It is best to be prepared.
Also, have several people you trust look at your portfolio. Get as much feedback as you can before you show it at interviews. Show it to your teachers, friends, or the Career Center at your school. This will give you time to make any necessary adjustments.

Thomas Nelson http://www.burnett.nelson.com/include.html

How to Organize a Portfolio

2005-03-04T01:05:00.000-08:00

You have collected the pieces you would like to include in your portfolio. You have sorted through your collection and selected your best work. You have made entry cards for each piece to provide a good introduction for each sample. And you are ready to place your work, introduction page, entry cards, section dividers, and give-aways into your new leather portfolio.

Where do you start?

Well, first start by conceptualizing how you want to present your work. This means that while you may want to include a marked up piece of editing in your portfolio to show that you do posses strong editing skills, you don't want to market yourself as an editor - since you have set your sights on working as a Web designer. So, do you put that piece of marked up editing in the front of your portfolio? Probably not.

Organize your portfolio to illustrate what your interests are. If you DO want to be an editor, fill the first part of your portfolio with marked up editing pages, recommendations letters of past employers where you worked as an editor, your STC chapter editing award, and anything else that screams, "I am the best editor in the universe! You must hire me, and you can see that by looking at all of my editing work!"

That doesn't mean that you can't or shouldn't include that document design project that you completed for a course, since it shows your skill with print design. And that Website you created shows your keen sense of color and layout. Print out a few pages of that and put it in there, too. But put it in the back, if that is where you think it should be.
So, it all depends on how you want to sell yourself.

Plus, the key to portfolios is neat and tidy sections. Clearly label and introduce each section and each piece. Make use of page dividers and tabs. Just think about how you can best get through the portfolio quickly. If the interviewer can see clearly marked sections, he or she might say, "Oh, there is a sample of graphic design, so it says on this tab. Let's take a look at that." If you didn't have those tabs, you would be thumbing through pages and pages of work that may or may not be desirable to the interviewer.

Think neat. Think clearly labeled. Think adequately introduced. Think about how you want to market yourself. Then organize your portfolio accordingly.

Also, have several people you trust look at your portfolio. Get as much feedback as possible. That will help you decide if you need to adjust the organizational structure of your portfolio.

Thomas Nelson http://www.burnett.nelson.com/organize.html

How to Create a Portfolio

2005-03-04T01:02:00.000-08:00

So, you decide that you would like to create a portfolio. What do you do? Where do you start?

First, realize that a portfolio is not something you can whip together the night before an interview. You should start planning your portfolio well in advance of interviews, perhaps even before an interview is scheduled or even approaching.

Second, you should start a collection, not just of your best work, but collect your money. You will need to save some money for this endeavor. You want your portfolio to be a professional representation of your work; therefore, be prepared to spend some money.

What to buy

- A nice leather portfolio, preferably burgundy in color: burgundy is recommended since you can carry it with virtually any color conservative suit. You want to make sure the portfolio rings are metal and sturdy. Open and close the rings several times before purchasing. If the rings look as if they are not lining up appropriately, ditch that one and try another. You don't want your work to crinkle because the rings are not lined up. You may want a portfolio with handles, so that you can carry like a briefcase. Look to see how many pockets there are in the portfolio, and see if they are large enough to insert bound pieces. You will want to utilize all space available.

- Quality paper, preferably white: white will not interfere with any of the colors in your pieces. Also, buy a ton of paper. You will need more paper than you think. As you show your pieces, they will become crinkled, so you will need to replace them with fresh pieces periodically.

- Card stock: you might want to invest in some card stock to use for section dividers. A nice neutral color is fine.

- Page divider tabs: you might want to use page-divider tabs to help show your different sections clearly. You can type the sections on the white tabs and insert them into the divider sheets. This allows for a clean, neat look that is easy to navigate through, quickly.

- Sheet protectors that allow top loading: these will help protect your pages through the many "look throughs." Top loading will just ensure that you can easily remove a piece if the interviewer wants to get a closer look. You can also keep "giveaways" behind the original, and a top-loading sheet protector will allow you to get the give a way easily.

- You will need to save money for copy costs, also: you may have to print several resumes, copies of samples, etc.

Thmoas Nelson http://www.burnett.nelson.com/create.html

Why Technical Writers Should Create a Portfolio

2005-03-04T00:59:00.000-08:00

Your projected graduation date is coming up. You are preparing your resume, including on-line, paper, and ASCII versions. You have been practicing your interview questions. What are you missing? You are missing your portfolio.

Why do you need a portfolio?

It isn't required, but it is a good idea to bring a portfolio to your interviews. There are several advantages to having a portfolio:

- Instead of merely telling the interviewer about the work you have done and the skills you have, you can actually show evidence of those skills.

For example, let's assume you are a technical writer who has experience in software applications such as Adobe Photoshop and Illustrator. You have created graphics for both print and online projects. Why not show them off? Why not say, "I can use these software applications, and here is sample of what I can do." Showing is always more effective than merely telling.

- When you have a well-organized portfolio that contains sample of your best work, you can show your wide range of talents. It is important to have only your best work in your portfolio. You show clear evidence of your skills and talents when you can show a portfolio that serves as visual support for your resume.

- You can use your resume to help focus on your desired area of expertise.

For instance, all technical writers know that the field is very diverse. There are technical writers who are editors, and there are technical writers who are Webmasters and Web designers, focusing on graphic arts instead of editing content. With such a broad definition of the field, a portfolio can help define your niche in the field.

- When you have a portfolio, suddenly, you can guide the direction of the interview, controlling the meeting.

For instance, when you are asked about your skills, you can show your portfolio - your best work. This often is intriguing to interviewers, and they want to see more. It's a wonderful feeling to have the opportunity to discuss all of your best work, your skills, and your talents, while showing the interviewer what you can do. Now, you guide the direction of the interview with your portfolio.

- When you have a portfolio, and you have sample "giveaways" to leave with the interviewer, you have left a visual reminder of who you are and what you can do. That is very powerful.

Thomas Nelson http://www.burnett.nelson.com/why.html

Usability in Technical Writing

2005-03-03T01:26:00.000-08:00

"Well-written" manuals are not good enough.

To most technical writers, "well-written" has traditionally been their quality goal for the User's Guide, online Help, and other information elements they developed. "Well-written" meant things like clarity of text and accuracy of grammar, spelling, and punctuation.

These are important characteristics to achieve. But, what should be our ultimate goal when we design information for people who want to quickly and easily do things with our software?
The answer is in the question. People want to quickly and easily perform tasks with our software. Therefore, the quality goal for information should rather be to help improve the ease-of-use of software. This means all our efforts and deliverables should be focused on making that
possible.

Enter UCID

User-Centered Information Design (UCID) is an integrated approach to designing various information elements such that they together improve software usability.

In UCID, the design stage is iterative and evaluation is a two-level activity. Technical writers, in collaboration with usability engineers and software engineers, primarily design and write all the four information components that impact software usability:

- User interface labels: names of all those things on the user's screens (for example, names of menu options)

- Application messages: error messages, warning messages, etc

- Online documentation: all the information elements that appear on the screen (for example, Help and tutorial)

- Printed documentation: all the paper-based manuals such as User's Guide and Reference Manual

Benefits of UCID

By giving a software usability driven approach, UCID puts you on the right track toward designing information. The UCID approach covers new strategies for the design and evaluation of information. The critical design goals you set and the two-level evaluation approach keep your information development efforts focused on improving software usability.

A UCID project makes full use of the technical writer's skills. Writers now have an expanded and challenging role that includes the design of labels and messages.

UCID brings you the advantages of integration. The UCID process ensures that individual information elements (error messages, screen-level Help, User's Guide, etc) are identified and designed together as one piece — with improved software usability as the goal. This means you make better decisions on what types of information to provide in which media and in what form -- based on users' needs and your project-specific requirements. Through integration, you will avoid four undesirable things: exclusion of critical information, inclusion of unnecessary information, unnecessary repetition, and information inconsistencies across the software system.

By helping you meet users' information requirements, UCID achieves improved software usability, which ultimately impacts the software organization's image and bottom-line.

http://www.tech-bridge.com/ucid.html

Justification for Documentation Testing

2005-03-01T22:41:00.000-08:00

Is documentation testing a part of your production process? If not, don’t you think that it should be? Generally, Technical Writers work to tight schedules, which often does not include documentation testing because there is no time. Besides, who wants to take the risk of causing a rewrite or correcting product design and not shipping on schedule? Nobody! What is needed is a justification for including documentation testing in the production schedule.

In "Liability for Defective Documentation," Cem Kaner provides valuable justification for documentation testing to ensure quality. Bad documentation, he says, has a ripple effect on the number of users it impacts such as Product Development, Training, and Customer Support.

Effect of Quality Documentation on Product Development:

- The manual provides an overview of the program. Despite best efforts by Quality Assurance to evaluate the program, a thorough test of the manual against the program is likely to highlight problems that were overlooked.

- New programmers and testers who join the project can use the manual to learn the program..

- Many product development groups stop maintaining the external specification and rely on the manual to serve this purpose.

Effect of Quality Documentation on Training:

- Customers will need less training and can proceed more quickly to advanced training if the manual is high quality.

- If the Training department likes and trusts the manual, it will use it for training purposes, saving the company time and money.

- If the manual is of high quality, the Trainer can use it to reinforce tips and tricks during the session. This can give a real "piece of mind" boost to the company.

Effect of Quality Documentation on Customer Support:

- It takes less time and costs less to prepare answer books – A well-organized Support staff prepares books or a database of answers to the questions that they expect will be frequently asked, or that will be difficult to answer.

- It makes calls take less time – Sometimes the best way to handle a call is to alert the customer to the relevant section of the manual.

- It results in less difficult calls – There’s nothing Support staff like less than dealing with customers that were misled by the contents of the manual. Imagine dealing with a person who has followed the instructions but wasn't able to achieve the result that the manual promised, or worse, who followed the instructions but lost data or got into trouble. Such calls can discourage Support staff.

Every Technical Writer has experienced resistance to doing what is necessary to thoroughly test manuals. To people who care about quality, you are talking about customer satisfaction. To people who care about schedules, you are talking about efficiency because a well-tested manual helps to train Development and Support staff faster. To people who care about saving money, you are spending a little to save a lot. To people who are afraid of making decisions, you are providing a business case that makes this decision look safe and obvious.

By: David Dick at http://www.stcsig.org

Technical Writing Course

2005-03-01T01:01:00.000-08:00

Virtual University of Pakistan has announced admission in Technical & Business English Writing short course. Students can study at any of the Virtual University campuses or from home. The duration of the course is 18 weeks, starting from March 7, 2005. The total fee is Rs. 2,000 inclusive of Tutorial Guidance, Discussion Board Visits, Mid and Final Term Exams etc plus Rs. 500 for course material (CDs & Lecture Handouts) within the country. The registration fee (one time only) for new students is Rs. 500. Last date to apply is March 5, 2005.

Click for more information

Effective Writing: Deadwood Phrases

2005-03-01T00:50:00.000-08:00

Deadwood phrases are found in all types of writing. In technical writing they are to be avoided at all costs as documentation needs to be crisp, concise and accurate.

You can improve your writing by cutting these out and replacing them with better expressions.

The following is a list of the ‘most wanted’ culprits.

The "deadwood" is in bold; use the suggested term instead.

- a majority of -- most
- a sufficient amount of -- enough
- according to our data -- we find
- accordingly -- therefore, so
- after the conclusion of -- after
- along the lines of -- like
- as is the case -- as is true
- ascertain the location of -- find
- at such time as -- when
- at the present time -- now
- at this point in time -- now
- be deficient in -- lack
- be in a position to -- can, be able
- by a factor of two -- two times, double, twice
- by means of -- by
- come to a conclusion -- conclude
- despite the fact that -- although
- due to the fact that -- because
- during the time that -- while
- equally as well -- as well, equally well
- fewer in number -- fewer
- for the purpose of -- to, for
- for the reason that -- because
- for this reason -- thus, therefore
- give consideration to -- consider, examine
- give indication of -- show, indicate, suggest
- happen(s) to be -- am/is/are
- has been proved to be -- is
- if conditions are such that -- if
- in a number of -- several, many
- in all cases -- always
- in case -- if
- in close proximity to -- near
- in excess of -- more than
- in large measure -- largely
- in many cases -- often
- in most cases -- usually
- in no case -- never
- in order that -- so that
- in order to -- to
- in some cases -- sometimes
- in terms of -- in
- in the amount of -- for
- in the case of -- for
- in the event that -- if
- in the field of -- in
- in the near future -- soon
- in the neighborhood of -- near, about, nearly
- in the vicinity of -- near
- in this case -- here
- in view of the fact that -- because, since
- is capable of -- can
- is found to be -- is
- is in a position to -- can
- it has been found that -- (nothing)
- it has long been known that -- (nothing)
- it is a fact that -- (nothing)
- it is evident that -- (nothing)
- it is interesting to note that -- note that
- it is noted that -- (nothing)
- it is our opinion that -- we think
- it is possible that -- perhaps
- it is well known that -- (nothing)
- it may be said that -- (nothing)
- make inquiry regarding -- ask about, inquire about
- manner in which -- how
- not with standing the fact that -- although
- on the basis of -- from, because, by
- on the order of -- about, approximately
- present in greater abundance -- more abundant
- prior to -- before
- provided that -- if
- put an end to -- end
- reach a conclusion -- conclude
- serves the function of being -- is
- subsequent to -- after
- the question as to -- whether
- there can be little doubt that -- probably
- utilize or utilization -- use
- with reference to -- about
- with the exception that -- except that

Deadwood is also found in excessively wordy writing. In other words, where writers use two or three words when one will suffice.

http://www.klariti.com

The Shifting Technical Writing Market

2005-03-01T00:30:00.000-08:00

Here's a disturbing statistic: According to a recent study, there are more technical writing jobs available than there are writers to fill them.
Run that by me again?

If there is a technical writer shortage, why then are there unemployed writers? And if you are unemployed, well, does being unemployed mean that you aren't very good at your chosen profession?

Let me answer the second question first: No. In my experience, the job weeds out those who aren't very good at it. The fact is that technical writing is one of the most demanding professions a person can practice. If you have survived and done reasonably well for more than two or three years, you're doing just fine.

Now for the first question. I believe that technical writers, by and large, do a poor job of marketing themselves in a competitive business. We cannot simply send resumes out anymore and expect the employers to come to us. The market moves too quickly for that. And business is changing: We're about to start moving even faster.

Business Acumen and Self-Promotion: The high tech industry is undergoing radical change -- as if that were anything new. But the change isn't happening so much in the area of technology as it is in the area of business intelligence. Well-run businesses are market driven, not technology driven, so it is important to understand not only the technology of the products we document, but the business problems that the technology solves. Writers must therefore also understand their company's business in a much broader way than ever before and learn to apply that business knowledge in the creation of new information products.

Technical writers must evolve. We must reinvent ourselves and be market-driven if we wish to remain employed and have interesting, challenging work to do. The days of being able to pull out a few binders full of detailed specifications that you can distill into a nice installation, configuration, or maintenance manual are long gone for most of us. Companies can no longer afford to have engineers "wasting" their time producing specifications.
Rapid development techniques have become the prime movers of today's product development cycles, fracturing traditional business, production,and documentation processes and requiring us all to approach what we do differently.

Trend Spotting: We must stay on top of the business and development trends that allow us to survive and thrive in today's business world. Today's hottest trends for technical writing include:

- Deep integration of technical writers into early development cycles to help create design specifications. Such specifications represent much of the company's intellectual capital, which is worth millions. Who better to manage the recording and maintenance of engineering intellectual property than a technical writer?

- The need for better technical marketing materials. White papers, competitive analyses, business intelligence, newsletters, data sheets, and technical product stories deliver compelling information to potential customers. Advertising gimics do not work -- people want to read about the benefits that your company's technology delivers.

- The need for consistent proposals and technical sales materials. The large account selling process is a game of inches, won by those account teams who present the most consistent message to the potential customer. Technical writers can create request for proposal (RFP) databases that enable busy sales people to assemble consistent, accurate RFPs. And they can maintain those databases far more effectively than a sales person or sales engineer can. Help the sellers sell, and you help yourself -- and those around you -- stay employed.

- The death of user guides. User guides are catalogs of user interface design errors. Technical writers must move deeper into the product management and development cycles to influence and help improve product usability. Though sometimes a hard sell, it is imperative that technical writers and their managers increase their personal marketing efforts to educate product management and engineering development. Technical writers are, after all, among the first users to figure out a product. Why not make use of that to help improve product usability?

- Web site content creation and maintenance. Technical writers are uniquely positioned to address the Web site content creation and maintenance problem. Good corporate Web sites feature useful, updated content to offer customers information that helps them solve their business problems.

- Knowledge management. Technical writers instinctively know that knowledge management is the record of a company's collective wisdom. Technical writers will play key roles in capturing that knowledge and making it accessible by those who need it.

- The demand for expertise in specialty areas. The Bureau of Labor Statistics tells us that the need for writers with expertise in areas such as law, medicine, and economics will likely increase because of the continuing expansion of scientific and technical information and the need to communicate it to others.

Now more than ever before, technical writers must learn to market and promote themselves, and add business acumen to the skills they offer. In so doing, we make a better work life for ourselves and for the people we serve.

By: Michael Knowles

The Future of Technical Writers

2005-02-17T05:07:00.000-08:00

Can technical writers be writing and communication specialists and remain successful at their craft, even if they have little or no knowledge of the technology they are documenting?

This topic is debated constantly on TECHWR-L (the technical writers mailing list). While there is no black and white answer, it is generally agreed that if two writers have comparable writing, communication, and editing skills, the writer with more knowledge of the subject matter will produce better results.

The slump in IT has caused employers and recruiters to request longer wish lists of technology experience for technical writers they will hire. While this frustrates writers searching for work, it is a trend that I do not believe will change.

A writer with strong technical knowledge in one or more areas can add tremendous value. As writers, we should not fear this trend. Rather, we can use this judgement by employers to increase our workplace value.

My advice is to pick no more than three strong technologies in your geographical area, and learn all you can about them. Join professional associations, take training courses, read industry publications, visit web sites, and speak to SMEs. When jobs are advertised in these areas, you will have an advantage over other generic applicants.

In the future, technical writers may become more ‘vertically’ oriented within markets, and most may work as contractors. They will be called in for short periods of time when documentation needs are high, much like a framer or drywall specialist is called in at the proper stage when building a house.

By: Gerry Loiacono twblog@aztec-it.com.au

Effective Wrting: Itemization

2005-02-14T22:42:00.000-08:00

Repetition of structure is effective in making long sentences easy to read. Itemization is another important device for making a sentence containing several long parallel elements easy, perhaps possible, to read. Itemization can also be used to emphasize the individual parallel elements.

The test indicated

-That continuous thermal exposure degraded the strength of the composite material.
-That cyclic thermal exposure did not degrade the strength of the composite material.

In the above example, the common element, that would usually be included in the introductory clause: "The test indicated that."

In an itemization, all items must be the same grammatical construction, for example, all prepositional phrases, all noun phrases, or all complete sentences:

Poor: Continuous cyclic exposure resulted in

- The matrix diffusing to the reaction layer.
- Degradation of the strength of the composite material

Better: Continuous cyclic exposure resulted in

- Diffusion of the matrix to the reaction layer
- Degradation of the strength of the composite material

Poor: The investigation was conducted

- To determine mechanisms causing strength degradation
- Because the rate of degradation varied widely depending on the composite matrix

Better: The investigation was conducted

- To determine mechanisms causing strength degradation
- To explain the wide variation in degradation rate for various composite matrixes

A Handbook for Technical Writers and Editors, Mary K. McCaskill

Movie: The Technical Writer

2005-02-10T03:17:00.000-08:00

Synopsis: A man who has grown weary of society over the years spends most of his time locked up in his house writing computer manuals, only coming outside to buy food. But his wild neighbors eventually convince him to open up, and when he does, he discovers a part of himself he thought no longer existed. More

Gender-neutral Technical Writing

2005-02-01T23:35:00.000-08:00

In recurring discussions on the TECHWR-L list, many technical writers argue that they write in "correct English" and are not going to change their style just to suit the political-correctness police. "I won't use 'they' as a singular pronoun because it's not grammatically correct" and "Using contrived phrases such as 's/he' is just too awkward" are arguments I've heard frequently in the debate. But using "incorrect English" or contrived phrases is neither the goal nor the outcome of gender-neutral writing.

Gender-neutral writing uses language that does not stereotype either sex nor appear to be referring to only one sex when that is not the writer's intention. In this article, you'll see why gender-neutral writing is important for technical writers to use, what gender-neutral writing is not, and how you can use gender-neutral writing in the documents you develop.

Why Should Technical Writers Care?

Why should technical writers care about gender-neutral writing? The answer is simple: Technical communication's goal is to convey information to an audience, in a form that the audience can understand and use. We should avoid, if possible, anything that interferes with clear communication. If part of our audience is insulted (or offended, irritated, confused, or misled) or stumbles over the way we express ourselves, that reaction will interfere with the reception and understanding of our message.

Additionally, using gender-neutral writing can help ease the document development process by avoiding issues that others on your team may raise. For example, some reviewers on your team may think that gender-neutral writing is an important issue, an opinion that distracts them from doing their real reviewing job. Instead of arguing that language is our job, not the reviewers' business, we could save ourselves a lot of hassle by avoiding potential problem areas. Or perhaps an editor may alert you to such issues, which may result in needing to rewrite passages late in the document development process.

If you dislike the whole idea of gender-neutral writing, you may find yourself using a lot of annoying alternatives (e.g., repeated use of the phrase "he or she"). However, you can produce writing that is gender-neutral but that is not awkward and does not mangle or revise the English language.

You may think gender-neutral writing is a good idea but of low priority. After all, you have only so much time, and your first priority is for the document to be complete and correct. I won't argue with that, but I know that with a bit of practice, you won't need to think about gender-neutral writing; it will just come naturally and won't take any longer than writing in any other style. Consider this: Many people had to pay a lot of attention before they learned to write naturally in active voice and plain English, but I hope we appreciate their value to clear communication.

If you're keen to improve your writing, you'll find gender-neutral writing a creative challenge. I won't say it's always easy, especially when your job is to revise existing material. I will say that I rarely meet a construction that I can't change into gender-neutral language. Out of context, a sentence may seem intractable; in context, it's frequently not a serious problem.
A word of warning: Some of the books (usually for business writers) that purport to cover gender-neutral writing include appalling collections of examples. Although their examples of phrases to be avoided is often quite comprehensive and good, their suggested solutions are frequently tedious, annoying, and trivial.

What Not to Do

If you've been thinking that you have to break grammar rules to use gender-neutral writing, you may be surprised at what not to do:

- Do not use "he" as a generic pronoun; use it only to refer to men and boys.
- Do not use "she" as a generic pronoun; use it only to refer to women and girls.
- Do not use "they" as a singular pronoun unless you are confident that your audience won't mind. This usage is gaining in popularity and acceptance, but a lot of people dislike it or stumble over it.
- Avoid phrases such as "he or she" and "he/she" or made-up words like "s/he."
- Do not use a feminized noun (e.g., manageress) when the normal noun (manager) covers both sexes.

What to Do

With what not to do in mind, here are some techniques you can use:

Bypass the problem of gender whenever possible For example, when writing procedures and instructional material, you are usually speaking directly to the reader, so you can use:

- Imperative mood (Do this.).
- Second person (you) instead of third person (he, the user).
- First person plural (we), as used, for example, in parts of this article.

Use plural nouns and plural pronouns Avoid problems with using singular nouns and pronouns by using plural ones, like this:

- No To log in, the user must enter his login name and password.
- Yes (In a user document) To log in, enter your login name and password.
- Yes (In other documents) To log in, users must enter their login names and passwords.

Avoid pronouns completely when you can Instead, try these techniques:

Repeat the noun (sometimes this also makes your meaning clearer):

- No Technical documentation exists for the reader. You are writing it for him, not for your ego. - Yes Technical documentation exists for the reader. You are writing it for the reader, not for your ego.

Use "a" or "the" instead:

- No The writer should know his reader well.
- Yes The writer should know the reader well. Rewrite the sentence or passage In some cases,

you may need to rephrase the sentence, like this:

- No Each user has his own login name and password.
- No Each user has their own login name and password.
- Yes Each user has a personal login name and password.

In other cases, you may need to rewrite an entire passage, like this:

- No The successful applicant will use his skills to contribute to the commission's work in remote areas. He will be posted to various locations during his two-year appointment. His removal costs will be paid, and he will be entitled to one return airfare each six months to the capital city of his choice.
- Yes (If a report, before the person is selected) The successful applicant's skills will contribute to the commission's work in remote areas. The person will be posted to various locations during a two-year appointment. Entitlements include removal costs and one return airfare each six months to the capital city of the person's choice.
- Yes (If a recruitment advertisement) As the successful applicant, you will use your skills to contribute to the commission's work in remote areas. You will be posted to various locations during your two-year appointment. Your removal costs will be paid, and you will be entitled to one return airfare each six months to the capital city of your choice.

Use a mixture of male and female names and scenarios in examples, unless the situation clearly cannot include both sexes (e.g., in a medical text discussing pregnancy, the doctor can be male or female, but the patient is always female). You can then refer to John as "he" and Mary as "she." Similarly, beware of stereotyping the senior person as the male and the subordinate person as the female, but don't use reverse stereotyping for everyone either.

Use generally-accepted titles Job titles are usually not a major problem in technical writing; for example, jobs in the IT (Information Technology) industry tend to have gender-neutral titles (as in, engineer, programmer, analyst, project leader, technician, manager, assistant, sales representative, and service engineer). However, keep in mind that your audience may be working in any field, so use titles that are generally accepted in your audience's industry, just as you would use other industry-specific terms.

Use other strategies, as necessary Finally, although the techniques mentioned here will help you develop and revise documents to be gender-neutral in the vast majority of cases, you may need to explore other resources and techniques. Some technical communications may need to distinguish between the reader of the document ("you") and someone else. For example, a specifications document might be written for programmers but be about the activities of end users. In these situations, you may need to use other writing strategies or examples, specific to the type of document you're developing.

Conclusion

Using gender-neutral writing does not mean that you use awkward constructions or non-standard English; instead, it simply means using language that does not stereotype either gender or refer to only one gender when that is not the writer's intention. By making a few minor changes to ensure your writing is gender-neutral, you can avoid distracting your audience and contribute to clearer communication. In the process of doing so, you may also find that you avoid potential problems during the document development process. The techniques and examples offered in this article provide a good starting point for using gender-neutral writing in the documents you develop.

Jean Hollis Weber

Being a Technical Writer

2005-01-23T21:57:00.000-08:00

What's the difference between a technical writer and a technical writer? Depends on who you ask, but it can often be measured in tens of thousands of dollars annually, dramatically reduced frustration in working with developers and engineers, freedom to work more independently, effectively, and efficiently than you thought possible, and even in the ability to telecommute or freelance more readily.

Truly being--or becoming--a techie writer requires that your perspective shift from being a consumer of information (provided by developers or other experts) to being both a consumer and a co-developer. While you may very well not write a line of code that anyone ever sees, the shift in perspective can allow you to play effectively in the developers' sandbox. That is, you need to be seen by developers as a contributor, a peer, an equal, and someone who "gets it." Once you reach this milestone, you're in, and you start to reap the rewards.

But what are the potential benefits of becoming a techie writer? And what are the costs?

Potential Benefits of Being a Techie Writer

Being a techie writer has many potential benefits:

Techie writers are in demand To begin, a techie writer has the potential to be more in demand than less techie writers. Think back to basic economics and the laws of supply and demand. If there are fewer technical writers than technical writers, it stands to reason that the fewer will be relatively more valuable than the latter. And, if you think through the ranks of technical writers you know, you'll quickly note that far fewer have the emphasis on the technical than on the writer.

Techie writers tend to be seen as more valuable, In hiring processes I've been involved with (both formally and as an informal, whatcha-think-Eric consultant), technical skills make a world of difference. A lack of technical skills usually drops a candidate to the bottom of the pile, at least if there are no signs that the candidate is making efforts to change the situation. Raw technical skills with poor communication skills often drops a candidate to a lower spot in rankings; however, setting overall quality aside (as often happens in the real world), it's more likely that a techier individual can hit the ground running and churn out somewhat acceptable content in short order than a less techie individual could do. Thus, the techier candidate is more likely to pop back up to the "interview-again-or-hire" pile as the supply of elusive ideal candidates is determined to be nonexistent. A candidate who demonstrates a good balance of strong technical skills with good communication skills is extremely rare, but often writes his or her own ticket.

Techie writers can demand higher salaries than less techie writers, Taking the Silicon Valley market for example, strong technical skills can return as much as $25-50 dollars more per hour for contractors. That is, an acceptable, moderately senior writer who would bill at $50/hour in most cases could increase the billing rate to $75-$100/hour (at the extreme) with better technical skills. In the full-time permanent arena, the delta can be as much as $20K through $40K annually, plus options, bonuses, and other perks.

Techie writers tend to experience fewer employment delays or gaps, These higher rates can come without unneeded delays in finding work as well. I know of many technical writing contractors who bill upwards of $100/hour through agencies, thus netting around $75-$90/hour, and have less than 10 hours of downtime between gigs. Some Bay area companies are currently paying bonuses of $5000 for referrals for good techie writers. With that level of interest, the downtime between jobs tends to be minimal.

Techie writers can help overcome common workplace challenges, Perhaps just as important, being a techie writer can also improve your work environment. As most practicing technical writers would attest, you don't have to look very far to find developers who have been burned by writers who don't contribute--or worse, who are just plain liabilities--because of an insufficient grasp of the technologies. Once bitten, twice shy, and you'll find that, as a writer, you must first prove that you're not a liability, then start doing your job. That said, if you can speak the language of the developers, work with them on their terms--not yours--and play an active role in getting the product to ship out the door with both solid code and information products, you'll find that your work environment borders on the ideal.

For example, after hiring a new writer, I checked with the lead engineer to find out how the initial encounter went. The engineer said, "She'll be fine to work with. Doesn't yet know it all, but has the background and asks good questions. No problem." So, you think that writer would be complaining about lack of respect? In my experience, you'll have fewer obstacles with the developers if you can speak their language, use their development tools, and understand their processes and challenges.

Techie writers can often work more independently and have more workplace flexibility, Being a techie writer may also offer you more freedom to work independently, effectively, and efficiently than you thought possible. How so? First, if you're willing and even marginally able to get your hands dirty (with code, with hardware, with equipment, or whatever), you gain a great measure of independence. You can test and tinker with the code, you can look and see (and fix) problems that you find (like typos in dialog boxes) and you can insert your own help IDs and help-system hooks, without having to wait for developers to find the time to do so for you. Finally, you can, in general, more easily control your work environment and minimize the time you spend on mundane tasks by automating or eliminating tedious processes.
Second, technical sufficiency may enable you to telecommute or freelance more readily than if you don't have the necessary technical skills to support yourself technical away from the office. Why? Because you are

More valuable to employers, thus they are more willing to accommodate your needs and wishes
More able to support yourself and resolve your own technical issues with little or no help
More able to know when a problem really is serious and requires external intervention

A non-techie writer will often have real difficulties in telecommuting or setting up an independent work environment. Although it is possible for non-techies to telecommute, doing so often requires extensive setup and support, which requires additional resources. Is it worth the hassle to have a less techie writer telecommute? Probably not. If there's no problem or hassle, is there any reason you shouldn't? Good question.

Potential Costs of Being a Techie Writer

Depending on your goals and inclination, however, becoming a techie writer may be costly:

Techie writers may not write as much, The time you spend in honing your technical skills and abilities is time that you necessarily don't spend in honing your writing skills and abilities. For some, that's not a problem. For others, that may mean curbing a passion or inclination for writing and related skills.

Techie writers may be seen as programmer wannabes, Rather than being seen as a techie writer, you may be seen as a programmer wannabe, which can be a disadvantage in all circles. Hiring managers can, in some cases, be threatened or negatively influenced by highly-technical writers, or they might pass over qualified applicants out of fear that they'd quickly jump ship to join the ranks of developers.

Techie writers may not relate to less techie audiences as well, As a techie writer, you can easily lose empathy and understanding for your readers. While acting as a user advocate is nearly always a part of the job description of an effective technical writer, as a techie writer, that will become ever more difficult. Absent conscious effort, you'll eventually forget how hard your technical knowledge was to achieve and how far ahead of your average reader you are.

By: Eric Ray

Technical Writing, Code of Good Practice

2005-01-04T23:43:00.000-08:00

1- Do not burden readers with information they do not need - they have more than enough difficulties in handling the information they do need.

2- It is the reader's need for information that shall be fulfilled - not the communicator's store of information that shall be emptied.

3- The communicator shall be able to choose freely the means of expression that are the most effective with regard to the reader and the defined goals.

4- The medium is not the message. [I have designed the book, now I shall write it]

5- The communicator is responsible for the intended reader's understanding of the technical message.
An information problem can often be solved in many ways - seldom is only one solution right and all the others wrong.

6- The communicator must not surrender to irrelevant, subjective demands for changes of information.

7- The communicator should make changes in information products only when the alterations increase the effectiveness of the information.

8- It is not unclever to express oneself in a simple way.

9- The communicator must be aware of the legal and moral aspects of his or her communications.

intecom.org

writer's copyrights

2004-12-30T22:14:00.000-08:00

The freelance writer's or first-time novelist's dream is to make the sale. But what happens next? Usually a contract will be sent by the editor outlining the rights you will be selling in exchange for your fee. Knowing the basic rights that you own in your work and the terms used by the publishing world can help avoid some nasty disappointments down the road.

What Do You Own?

The original author of a work owns the copyright to that work, unless he or she has assigned those rights to a third party. Copyright protection arises automatically, without any action taken by the author, the moment the work is fixed in a tangible form so that it is perceptible either directly or with the aid of a machine or device1. The owner of a copyright really owns a "bundle" of rights, like a bundle of sticks. Each stick or right can be sold or assigned separately to a third party.

Types of Rights Commonly Sold by Freelancers

First Serial Rights: A writer selling First Serial Rights is selling a newspaper, magazine or periodical the right to publish the story, article or poem for the first time in any periodical. All other rights remain with the author. First Serial Rights may be limited by geographical limits. For example, First North American Serial Rights ("FNASR") limits the license to periodicals published in North America, which includes the United States and Canada. First Serial Rights sold to an online publication cannot be limited by geographic area because the Internet is accessible by a worldwide audience.

One-Time Rights: A license of one-time rights, also known as simultaneous rights, grants the licensee the right to publish the work one time. This is a non-exclusive right which means the author may sell one-time rights to several publications at once -- normally to publications with different audiences.

Second Serial (Reprint) Rights: A license of Second Serial Rights gives the publication the right to publish the story, article or poem after the piece has already been published by another periodical. Second Serial Rights are nonexclusive; the author may license the piece to more than one publication.

All Rights: A license of All Rights is exactly that; the author is giving up all rights he or she owns in the work. The publisher may publish the work in any format -- print, film, electronic formats such as CD ROMs, and on the Internet without providing additional payment to the author. The author retains the right to state that he or she authored the work, but loses all the other rights to the work, including the right to publish, market or distribute the work, to create derivative works, or to perform the work.

Subsidiary Rights: In a book publishing contract, subsidiary rights are all rights owned by the author other than the right to publish the book. Subsidiary rights are negotiable in a book contract and will cover such potentially valuable rights as movie, film, videotape and audiotape rights, electronic rights such as CD ROM publishing, translation rights, book club rights, foreign rights etc. Subsidiary rights may be retained by the author so that the author's agent can negotiate separate deals for each of the rights, or the subsidiary rights may be sold to the book publisher so that the publisher can negotiate the rights. Each situation is different, however, many author's attorneys advise authors to retain the subsidiary rights on the grounds that the author's agent or attorney can obtain a more favorable deal for the author than the publishing house will.

Dramatic, Television and Motion Picture Rights: These are the rights licensed when selling work for use in a play, television or film. Most commonly, a work will be optioned under the following terms: the author is paid 10% of the agreed upon purchase price of the work, in exchange for the exclusive right to market and produce the work. The usual time limit for an option is one year. If the option expires and is not exercised, the author keeps the money and is free to option the work to someone else. Having a work optioned is no guarantee that it will ever be made into a film, play or television show.

Work For Hire: If an employee creates a work within the scope of the employee's employment, any work created belongs to the employer including the copyright to the work. This is called "work for hire". For example, a comedy writer for a sitcom writes the script for one episode. The script is the property of the employer, not of the writer because they were written within the scope of the writer's employment. The writer does not own the copyright to the script; the employer does. "Work for hire" can also occur in a freelance situation if the author signs a specially commissioned "work for hire" agreement before the development of the project. Unless an independent contractor (the writer, musician etc.) signs a specially commissioned "work for hire" agreement, the copyright to the work created will remain with the author of the work. If a specially commissioned "work for hire" agreement is signed, the copyright to the work created will belong to the developer of the project.

For example, Production Company wishes to develop and produce a documentary film. Production Company will enter into agreements with independent filmakers, writers, and musicians to create original work to which Production Company will own all the rights. In order to own the copyright to the finished product, Production Company will enter into specially commissioned "work for hire" agreements with each person who contributes original works to the final film. "Work for hire" agreements are common in the entertainment industry as well as in ghostwriting arrangements. The author must realize that if such an agreement is signed, he or she is giving up all his or her rights in the finished product forever. If a confidentiality clause is included in the contract (such as in a ghostwriting situation), the author cannot disclose the fact that he or she actually wrote the piece.

Electronic Rights: The licensing of electronic rights to a work in this day of expanding technological capabilities is a hot topic in the publishing industry. The best way to handle electronic rights is to clearly spell out exactly which electronic rights are being licensed and which are not. Electronic rights can encompass the rights to sell and distribute the work on CD ROM, to store the work in a database, such as Lexis-Nexus, to publish the work on the Internet, to archive the work on the Internet and the publishing of the piece on as-yet not invented electronic media. In a sense, the law of electronic rights is being written now by the writers, editors and publishers. Eventually, the terms will be recognized to have standard meanings in the industry. In the meantime, freelancers who write for online publications should ask the editor to spell out in plain language exactly what rights they are purchasing. If you don't understand what an editor means by "First Electronic Rights", then ask. Most editors are happy to explain their publication's policies. And keep copies of all the correspondence, whether it is by letter or by email. The correspondence itself constitutes a binding contract if it clearly shows what the parties intended.

Freelancers selling to the American periodical market should be aware of the recent court decision in Tasini v. New York Times, 93 Civ. 8678 (S.D.N.Y Aug. 13, 1997). In Tasini, District Court Judge Sotomayor ruled that in the absence of a contract that publishers are entitled to place all of the contents of their printed publications into an electronic database such as Lexis/Nexus or onto CD-ROM without the freelancers' permission and without compensating them for reprints. Judge Sonia Sotomayor based her decision on the U.S. Copyright Act which allows reprints without freelancer's permission or compensation if the freelance work is part of a "collective work".

There are a couple of important points to keep in mind about this decision. First, the Tasini ruling was in the context of a summary judgement hearing; there was no trial. The ruling has been appealed by the Plaintiff, Mr. Tasini, the President of the National Writer's Union ("NWU"). Furthermore, the ruling applies only in cases where there is no contract between the freelancer and the periodical. Since Tasini, almost every major newspaper has instituted formal contracts with freelancers specifically covering archiving, database rights and other electronic rights. Although many freelancers are unhappy with the form of these new contracts -- which generally require the freelance writer to relinquish all rights, electronic or otherwise -- many are signing the contracts. Finally, the ruling is silent on the issue of Internet publishing and does not apply to situations where there is a contract between the freelancer and the publication.

Conclusion

The novice writer must learn the business end of the writing and publishing industries in order to survive. Most freelance writing agreements are not complicated documents and most writers are perfectly capable of understanding and negotiating their own contracts if they get in the habit of reading carefully, asking questions when they don't understand something, and taking the time to learn the basic terms used in the industry. The time spent researching these issues will be well worth the time spent. Most agents will not represent freelancers or short story writers because the compensation is too low for it to be worth their time and effort. However, there are certain situations when it is strongly advisable to have a knowledgeable agent or attorney do your negotiating for you. Book contracts, for example, are usually complex documents which contain a myriad of pitfalls for the layperson which, as a general proposition, should not be signed without having an attorney review it first. So, make time to learn the business basics of being a writer. After all, it's your work -- shouldn't you know what your rights are?

Clarie E. White
http://www.writerswrite.com/journal/sept97/cew2.htm

technical writer's resume

2004-12-29T20:44:00.000-08:00

FIRST OF ALL, above any considerations of technical aptitude, organizational habits, or familiarity with documentation technologies, you must be able to WRITE - and this must be displayed through your professional looking resume!

Of course you can write, you're a technical writer aren't you?

On the contrary, many people involved in the field of technical documentation concentrate solely on trying to be experts in the technology they are documenting, and completely ignore the fact that the knowledge they are developing must be communicated to someone else--most likely someone with far less technical aptitude. As a result, they view the material that they write as "dry" or "non-creative", and this underlying philosophy becomes very obvious through sentences and paragraphs that are lifeless and uninteresting.

YOU must show that you are different! Through your resume, you must convey the fact that you have a passion for technical documentation and understand its place in the overall communication environment.

Here is a a comprehensive list of qualities that the perfect technical writer would possess. A few of the main areas are briefly described below. It will be of EXTREME IMPORTANCE that you find a way to show these qualities to your audience through your resume - they will set you apart from the other candidates and increase your chances of getting the INTERVIEW!

Technical writer resume qualities #1

You must display/convey the ability to translate a morass of technical details into a clear hierarchy of concepts. Such a quality encompasses the ability to think logically, and then clearly communicate one’s thoughts to others. In many cases, the writer must have the ability to communicate this information in different ways, depending on the audience. This is, after all, what technical writing is all about.

Technical writer resume qualities #2

Point out that you have knowledge and give attention to document design. This is not about being a graphic designer. Technical writers must understand the relationships between various components of a document, and be consistent in applying them. Such attention to document design will help the reader understand the concepts being presented.

Technical writer resume qualities #3

Consistency in editing. The writer should have a solid understanding of the rules of the language he or she is working in, know how to use them properly, and know when those rules can be bent.

Technical writer qualities #4

Ability to plan one's workload. Another logical thinking quality, this ability allows the writer to take a murky collection of project requirements and translate them into a clear and comprehensive set of tasks. The resulting schedule that can be developed will help identify potential trouble areas, and minimize headaches for both writers and their managers.

Technical writer qualities #5

Proper and consistent reporting habits. This quality involves the ability to understand that tasks assigned by a manager are a priority, and that it is up to the writer to figure out when and how the task can be completed, or to alert the manager to potential problems and provide alternatives. It’s alright to be told how to do this the first few times, but it is a skill that the writer must pick up quite quickly.

Technical writer qualities #6

Establishing and maintaining a good rapport with clients. This starts with the client's first impression, so good presentation and appearance is a must, along with a pleasant demeanour. Writers should have the ability to identify a client’s requirements and then find a blend between what the client wants and what the writing team can offer.

Technical writer resume qualities #7

Good knowledge of documentation tools. These days, knowing how to properly use a wide range of wordprocessing packages or on-line help tools is crucial. Knowing how to use the tool is often a key aspect in integrating the final product into a client's environment.

Technical writer resume qualities #8

Desire and ability to learn new concepts. No one can be an expert in every subject area, but the technical writer is often required to write about a wide range of topics. Being able to perform research efficiently, and quickly pick up key knowledge components is a vital skill in ensuring the versatility of any technical writer.

Technical writer resume qualities - wrap up!

Of course, there are some qualities that will be more important to your prospective employer than others, and you will have to do your research and find out what your evaluators are looking for!

No writer will ever possess the perfect set of skills. The main goal for you should be to highlight core set of skills that your employer will be looking for - DO YOUR RESEARCH!

http://www.master-of-writing-resumes.com/writer-resumes.html

Automatically Repair Office Applications

2004-12-28T21:43:00.000-08:00

Caution

Choosing this option will discard many of your customized
settings and restore default settings. For instance, the following will be set
back to the state they appeared when you first installed Office:

The Assistant character selection
Most-recently-used entries on the
File menu will be removed
The size of the application window
for all applications
Menu and toolbar position and any
customizations
Customizations and additions to
Office Shortcut Bar
The security level for each
application
View settings within the application,
such as the Calendar view in Outlook

Your User Name and Initials will also need to re-entered when you restart
your Office applications.

On the Help menu, click Detect and Repair.

To restore the program shortcuts to the
Windows Start menu, make sure the
Restore my shortcuts while repairing
check box is selected.

Click Start.

Notes

This feature is not available for
Office applications earlier than Office 2000.

This procedure detects and repairs
problems such as missing files and registry settings associated with all
installed Microsoft Office programs. It will not repair personal files, such
as spreadsheets or documents.

If the
Detect and Repair command does not fix the problem, you might need to
reinstall Microsoft Office.

ways to reduce file size in MS Word

2004-12-21T02:44:00.000-08:00

Compress pictures: Compressing pictures can discard extra information — such as cropped areas — from the file, reduce image resolution, and where possible, make the graphics file format more efficient.

Turn off fast saves: Using fast saves to save a document requires more disk space while your document is open than using a full save. You may be able to save disk space by clearing the Allow fast saves option.

Embed only the TrueType font: Embedding TrueType fonts in a document increases its size. If you embed TrueType fonts, you may be able to reduce document size by selecting the Embed characters in use only option. This option embeds only the font styles used in your document. Also, if you used 32 or fewer characters of a font — for example, a few symbols or a headline — Microsoft Word embeds only those characters.

Delete versions: Creating multiple versions of a document using the Versioning feature may increase file size. To check whether a document contains other versions, click Versions on the File menu. If other versions exist, you may be able to reduce the file size by deleting the oldest versions.

Convert embedded objects into graphics: Adding embdded objects [embedded object: Information (object) that is contained in a source file and inserted into a destination file. Once embedded, the object becomes part of the destination file. Changes you make to the embedded object are reflected in the destination file.] to a document can increase its size. If you don't need to update an embedded object contained in a document, you may be able to reduce the file size of that document by converting the embedded object to a graphic. After converting the object, you can edit it just as you would edit any other Word graphic. After an embedded object is converted to a graphic, it can't be changed back to an embedded object.

Link graphics: Use a linked object [linked object: An object that is created in a source file and inserted into a destination file, while maintaining a connection between the two files. The linked object in the destination file can be updated when the source file is updated.] instead of an embedded object. With a linked object, you can easily update information in your Word document when the information is changed in the source file [source file: The file that contains information that was used to create a linked or embedded object. When you update the information in the source file, you can also update the linked object in the destination file.]. Linked data is stored in the source file. The destination file [destination file: The file that a linked or embedded object is inserted into. The source file contains the information used to create the object. When you change information in a destination file, the information is not updated in the source file.] stores only the location of the source file but still displays the linked data.

Creating Documentation in Microsoft Word

2004-12-13T21:31:00.000-08:00

To save costs, many small businesses take the do-it-yourself route to publishing product and support documentation. The tool of choice is often Microsoft Word - after all, you probably already have a copy of it and know how to use it reasonably well. But while using Word to *develop* your materials is an acceptable choice, using it to *publish* documentation is not! Read on to learn some of Word's shortcomings as a publishing method, and what alternatives are available.

SECURITY ISSUE #1: THERE IS NO "DOCUMENT SECURITY"

Simply put, there is no "document security" in Word. Anyone with a copy of your document can change the text, formatting, layout, form fields, your copyright notice, and so on. Word does offer password-protection for documents, but this doesn't prohibit the reader from changing anything while viewing it or saving it to another file name.

SECURITY ISSUE #2: CAN'T HIDE THE META DATA

Even more critical is "meta data" - private information such as the author's name (or network ID), name of the company your copy of Microsoft Office is registered to, total amount of time the document was worked on, and so on. This data is embedded automatically in every single Word document. To see what kind of information you could be leaking out, open any Word document and click on File / Properties.

Microsoft admits there is no easy way to remove all of the metadata information, although some of it can be "reset" via various procedures. Apparently an option exists in the new Word 2002 (Office XP) to make this easier, but again, it's not a simple procedure and the onus is still on you to remember to do it.

COVER YOUR TRACKS (TRACKED CHANGES, THAT IS)

Word has a feature called "Track Changes" that helps people sharing a document to track what has been changed and by whom. If you use this feature but forget to fully disable it before distributing your document, you now have an instant, visible audit trail of document revisions. If you had any sensitive information in there, consider it no longer private.

Alcatel, an American telecommunications company, fell victim to this mistake earlier this year when they published a Word-format press release concerning a known security vulnerability in their DSL modem products. Read the story at http://morons.org/articles/1/188.

THE INCREDIBLE SELF-INFLATING DOCUMENT

A 200-page Word document with 25 screen shots can easily total 5MB in size. Add more graphics or cross-references, and watch the file size magically balloon to 8MB or more. Your customers will probably not appreciate having to download a file of such a size, especially if they're on a slow dial-up connection - and especially if they're trying out your product before buying!
By the way, Word's "Fast Save" feature is NOT your friend - it is known to horribly bloat and corrupt documents when you least expect it. Turn off the "Fast Save" feature under Tools / Options / Save.

NOT EVERYONE OWNS A COPY OF WORD

Microsoft Word may be the world's most popular word-processing package, but that doesn't mean everyone has a copy of it. Customers may be using an operating system that doesn't support it, they cannot afford a copy, or they've found another word-processing program they like better.
What alternatives have you provided for these folks to use your documentation? Microsoft Word is an expensive program, and it's unfair to require customers to own a copy just to be able to read your user manual.

SO WHAT ARE THE ALTERNATIVES?

Granted, no publishing method is 100% perfect, but there are still a lot of options available to the do-it-yourselfer. Adobe PDF format, HTML web pages, and embedded Help files are excellent, low-cost ways to distribute your documentation while maintaining various levels of control over layout and formatting, security, file size, and accessibility.

Adobe Portable Document Format (PDF) files are like a "picture" of your original document, which means the text and layout cannot be easily changed. PDF's have a built-in navigation system called "bookmarks", offer excellent security, and are small in size. And best of all, you can still use Word to develop your document - simply convert it to a PDF file via a button in your Word toolbar! Your customers will require the free Acrobat Reader to view the files. Check out http://www.adobe.com/acrobat for more information.

HTML files are also small and load quickly, provided they are not too graphics-intensive. Every operating system today has a built-in or free HTML browser. However, it's recommended you leave out features such as frames, scripting, or Flash animation that many browsers do not support. You can use any HTML editor to create these files, and your Webmaster can make you a template to ensure the document style integrates with your overall website design.

Embedded help (commonly called "online help") are those screens that magically pop up when you click the 'Help' button in a program. Help systems can be embedded right into an application or distributed as small stand-alone files, depending on your needs. A single Help system can also be made viewable on several different operating systems. Two excellent Help Authoring Tools are RoboHELP (http://www.ehelp.com) and ForeHELP (http://www.forehelp.com).

Ultimately, the choice of which format(s) to use will depend on your individual situation... but in every case, there are excellent, low-cost alternatives available to publishing your documentation in Microsoft Word format. An experienced documentation specialist will be able to evaluate your situation and recommend the most appropriate options. Good luck!

Author: Tanja Rosteck
tanja@words4nerds.com