Technical Writing

Document Sample
Technical Writing Powered By Docstoc
					Technical Writing
 Izzeddin A. Matar
 Faculty of Information Technology University of Petra
                                                          Document Types
                                                                        Part 4
 The Mayfield Handbook of Technical and Science Writing Leslie C. Perelman, James Paradis Edward Parrett, Mayfield Publishing Company, Inc.
Document Types
    After identifying a document's purpose, determine the appropriate
     document type
         Memoranda
          Agendas
         Meeting documents
         Literature reviews
         Reports
         Letters
         Proposals
         Press releases
          Specifications
         Documentation
         Instructions and procedures
         Style guides
         Theses
         Oral Presentations
         Résumés
         Notebooks
          Or to Electronic document types such as: Electronic mail Web sites Hypertext
2.5 Letters
  Letters: to communicate outside your
   organization. Whereas the memorandum is
   the primary vehicle for communication within
   an organization
  letters are often used to communicate to
   individuals outside it, especially in formal and
   semiformal contexts.
  Letters are an essential part of all business
   and technical communication because they
   are more formal and reliable than electronic
   mail and more precise and permanent than
   telephone or face-to-face conversations.
Types of Letters
 The following are some of the most common
   types of letters written by people in technical
  Job application letters
  Acceptance letters
  Transmittal letters
  Inquiry letters
  Technical-information letters
  Letters of recommendation
Format of a Letter
 If your organization has a specific style for business letters,
  follow that format. Otherwise, follow the guidelines provided
  here. Business letters are commonly either full-block formatted,
  with every line starting at the left margin and usually a business
  letterhead at the top of the page, or modified-block formatted,
  with the heading and the closing aligned at the center of the
 Elements of a Letter
 Business letters have the following elements:
       Heading
       Date
       Recipient's address
       Salutation
       Body
       Closing
       End notations

  If you are not using letterhead stationery,
   begin with your full address (city, street, and
   zip code) 1 to 1½ inches from the top of the
  Spell out address designations, such as
   Street, Avenue, and West
  Postal Service designations.
  Include the date aligned at left with the
   address, spelling out the name of the month.
Recipient's Address -Business letters
   Two to four lines below the date, place the following
   The recipient's title (such as Mr., Ms., or Dr.) and full
    name (address a woman who does not have a
    professional title as Ms. unless you know she prefers
    Miss or Mrs.;
   if the recipient does not have a title and you are
    unsure of his or her gender, omit the title).
   The recipient's job title, if appropriate.
   The name of the company or institution, if appropriate.
   The full address, following the same format as for the
    address in the heading.
   The recipient's address is always aligned on the left
    Place the salutation two lines below the recipient's
    The salutation begins with the word Dear, continues
     with the recipient's title and last name, and ends with a
    If you are unsure of the recipient's gender and the
     recipient does not have a professional title, omit the title
     and, instead, use both the first and the last names in
     the salutation
          (Dear Leslie Perelman:).
    If you do not know the name of the recipient of the
     letter, refer to the department you are writing to
          (Dear Technical Support:).
    Avoid salutations such as
          Dear Sir or Madam:.
    Start the letter two lines after the salutation.
    Body paragraphs should be single spaced with a double space
     between paragraphs.
    (Indenting the first line of each paragraph is acceptable but is
     more informal than the unindented style.)
    Be concise, direct, and considerate.
    State the letter's purpose in the opening paragraph.
    Include supporting information in a middle paragraph or two, and
     conclude your letter with a brief paragraph that both establishes
     goodwill and expresses what needs to be done next.
    If a letter requires more than one page, make sure there are at
     least two lines of body text on the final page.
    Never use an entire page for just the closing. The second page
     and all subsequent pages must include a heading with the
     recipient's name, the date, and the page number.
Closing Phrase
  Write a complimentary closing phrase two lines below
   the final body paragraph.
   Yours truly, Sincerely, or Sincerely yours
 are common endings
  Capitalize the first letter of the first word of your
   complimentary closing, and end the complimentary
   closing with a comma.
  Four lines below the closing phrase, write your full
  If you are writing in an official capacity that is not
   included in the stationery's letterhead, write your title
   on the next line.
  Your signature goes above your typed name.
End Notations
  At the bottom of the last page of a business letter, end
   notations may show who typed the letter, whether any
   materials are enclosed with the letter, and who is
   receiving a copy of the letter.
  An enclosure notation-
 -Enclosure:, Encl., or Enc.--alerts the recipient that
   additional material (such as a résumé or a technical
   article) is included with the letter.
  You can either identify the enclosure or indicate how
   many pieces there are
  A copy notation (cc:) lets the recipient of the letter
   know who else is receiving a copy. Put each recipient
   of a copy on a separate line.
   Enclosure: Article by Dr Lolo shater
           Encl. (2)
           Enc. (2)

   cc:     Dr Fofo Mouse
            Mr. Lali Mater
2.5.1 Job Application Letters
   Write job application letters that identify a specific area of employment,
   Summarize your qualifications for the job, refer to an enclosed résumé,
    and request the next step of the application process, usually an
   Application letters are usually just one page and consist of three
        Front matter. State that you are applying for a specific job title or field.
         Also mention the person who referred you or told you about the job. If you
         learned of the job from an advertisement, mention that.
        Body. Explain specifically why you are qualified for the job. Describe
         education and work experience and any other activities that display
         relevant talents, such as foreign-language proficiencies and leadership or
         supervisory experience.
        End matter. Refer to your enclosed résumé and express your desire for an
         interview, stating when and where you will be available for one. In addition,
         invite further inquiries, and state how you can be contacted.
Application letter:
An Example
2.5.2 Acceptance letter: An Example
2.5.3 Transmittal Letters

    A transmittal or cover letter accompanies
     a larger item, usually a document. (to
     explain why something is being sent)
A cover letter
2.5.4 Letters of Inquiry
   A letter of inquiry asks someone for specific information.
   Consequently, always make the tone of the letter friendly and make it
    easy for the recipient to identify and provide the information you need.
   Format of a Letter of Inquiry Follow this format in writing a letter of
   In the first paragraph, identify yourself and, if appropriate, your
    position, and your institution or firm.
   In the second paragraph, briefly explain why you are writing and how
    you will use the requested information. Offer to keep the response
    confidential if such an offer seems reasonable.
   List the specific information you need. You can phrase your requests
    as questions or as a list of specific items of information. In either case,
    make each item clear and discrete.
   Conclude your letter by offering your reader some incentive for
of Inquiry:
An Example
2.5.5 Technical-Information Letters
and Memoranda
   ƒTechnical-information letters and memoranda are short
    documents that announce new technical information,
    such as a software bug and its solution, or a new feature.
    ƒUse the memorandum format if the information is being
    sent inside an organization. ƒUse the letter format if the
    document will be sent to outside individuals.
   The following example is adapted from a technical-
    information memorandum written by Information Systems
    at the Massachusetts Institute of Technology. The
    document informs users of MIT's Athena network of a
    change in the protocols of MIT's main World Wide Web
    (WWW) server that allows users to place shorter Uniform
    Resource Locators (URLs) in their WWW pages.
    Nearly the most employers read your résumé before
     they meet you, and their reaction to it usually
     determines whether or not they will consider you
     further by interviewing you.
    In addition, your job interviews will often start with
     references to your résumé.
    Consequently, spend considerable time in developing
     one or more versions of your résumé, each one
     targeted for a specific type of job.
    Your résumé must be readable, neat, and free of
     grammatical, spelling, and typographical errors.
    Because it is so crucial in the job application process,
     edit your résumé carefully and have someone else
     review it before you send it out.
   Effective résumés contain the following elements:
   Heading :The heading should contain your name, full address, and
    phone number, including area code. If you have them, you may also
    include a FAX number, an electronic mail address, and even your
    World Wide Web page (if you are sure that you want all prospective
    employers to see it).
   Professional or job objective :The objective statement is a short,
    one- or two-line description of the sort of job you want and the specific
    fields in which you are interested. It does not have to be a complete
   Educational history :Summarize your educational history in reverse
    chronological order, showing how it has prepared you for the sort of
    job you want. List descriptive titles (but not course numbers) of all
    relevant classes you have taken. If you have not yet received your
    bachelor's degree or if you have just graduated, include the name of
    your high school, the city and state in which it is located, and the
    dates you attended.
 Work experience List all relevant work experiences in reverse
  chronological order, using action to provide vivid and specific
  descriptions of all activities that are connected with your job objective.
 Your special skills, activities, and accomplishments directly
  relevant to your professional objective List any skill (such as
  proficiency in a foreign language or expertise in specific computer
  applications) that may be relevant to the position. In addition, list any
  activity or accomplishment that will provide a positive first impression of
  relevant personal qualities, such as your energy level and initiative, your
  ability to work with diverse groups of people, and your communication
  skills. Do not, however, list hobbies or memberships merely to fill out the
  résumé. Include only activities and accomplishments that a prospective
  employer may find relevant to the position.
 Reference statement In most cases, conclude your résumé with
  "References available on request." List the names of your references
  only if doing so is customary in your profession and only if you have
  secured explicit permission from each individual to include his or her
  name on your résumé.
Example 1:
Example 2:
Action Verbs for Résumés and Job
Application Letters

  Most employers want to hire active,
   energetic individuals.
  Use action verbs to emphasize and to
   describe vividly what you have done and
   accomplished. The following list provides
   a sample of effective action verbs to use
   in résumés and job application letters.
   acted analyzed assembled assessed briefed
    calculated coached compared compiled
    composed computed coordinated created
    demonstrated designed developed diagnosed
    directed edited established evaluated executed
    founded implemented instructed invented
    investigated led maintained managed negotiated
    operated organized performed planned prepared
    produced promoted reported researched
    restored reviewed searched surveyed
    synthesized taught tested worked wrote .
   In a proposal, identify a specific problem and state how
    you will solve that problem.
   Most organizations rely on successful proposal writing
    for their continued existence. You will most likely spend
    a major part of your professional life writing proposals.
   Proposals are carefully prepared and just as carefully
    reviewed by granting agencies.
   Proposals do not succeed on the strength of a name or
    as a result of flashy rhetoric. Rather, successful
    proposals demonstrate that you understand the scope
    of the problem (its background, theory, and application)
    and, furthermore, that you have developed a valid and
    well- focused approach for reaching proposed
   All proposals develop a plan of action in response to a
    specific need or problem. Some proposals are
    external, written in response to a request for proposals
    or an invitation to bid that has been published by an
    external organization. Other proposals are internal,
    written in response to a need within your own
    organization. In either case, your proposals must show
    that you understand the nature of the problem and that
    you have a specific and well-developed plan for
    arriving at a solution.
   Most proposals share a general structure for
    identifying the motivating problem, the objectives, and
    the proposed course of action.
Proposals - General structure

  Front matter
  Body
      Introduction
      Technical approach

      Management requirements

      Work plan

    End matter, or management requirements
  Front Matter
   The front matter of a proposal includes the following
            Letter of transmittal
            Title page
            Summary
            Table of contents
            List of figures and tables
      End Matter
            Bibliography
            Résumés
            Appendixes

Technical Writing                    Izzeddin A. Matar      36