Technical Writing

• Technical Writing
  An open analysis and guide -
  Abhilash Gopi.
  
  Introduction to documentation
  It is necessary to create documents having clear instructions, descriptions using appropriate headers, lists and graphics, handling numbers and abbreviations in a well organized manner.
  
  Writing Technical Reports
  A major document that requires a skilled technical writer is the Technical Report.
  A technical report warrants for some research on our part.
  The focus of the technical report is on
  -Writing ability,
  -Adaptation to the specific audience,
  -Readability
  -Flow of the content,
  -Organized content
  -Detail.
  
  Writing Technical Reports
  Focussing on the format, we need to know how to.
  -Use headings, lists
  -Incorporate appropriate graphics
  -Handling the font
  
  
  Technical aspects of the Report
  Before you start with the creation of the Technical Report, decide on the following
  
  Report topic : Decide what subject you are going to write on,
  Report audience : Define a specific group or person for whom the report is written,
  Report purpose : Define what the report will accomplish, and the needs of the audience that will be satisfied
  Report Type : Decide on the type of report (technical report, feasibility report, instructions etc.etc.)
  
  Types of Technical Report
  Technical Report can be categorized into the following
  Technical – Background report :
  - It is the most difficult of the technical reports, but the most common.
  - It provides background on any selected topic
  
  The information is put down for some group or individual that has specific needs and is even willing to pay for the information.
  
  Types of Technical Report
  Instructions report :
  
  - These are the simplest of reports
  - Typically written by students or workmen illustrating backup procedures for their jobs,
  - Is equivalent to a short manual (something for an appliance, equipment etc.)
  
  Types of Technical Report
  Feasibility, recommendation, and evaluation
  reports
  - This report is the outcome of a study or evaluation and then make a recommendation.
  
  - A feasibility report tells whether a project is FEASIBLE (that is practically viable).
  
  - A recommendation report compares two or more alternatives and recommends one.
  - An Evaluation or Assessment report studies something in terms of its worth or value.
  
  Types of Technical Report
  Primary research report :
  - It refers to the actual work done in a laboratory or in a field.
  - In this type of report, besides presenting the data, you will need to draw conclusions and explain the methodology, the equipment, facilities and the background of the problem.
  
  Types of Technical Report
  Technical Specifications
  
  - In this report, you discuss a new product , the design (based on construction, materials, functions, features, operation, and market
  potential).
  - This report makes extensive use of tables, lists, graphics.
  
  Types of Technical Report
  Proposals
  
  - Most proposals are huge, lengthy documents, This is because, most of the elements are imported from other reports (such as feasibility, discussions, review reports etc.)
  - It is very important to be as true as possible to the topic that was selected.
  
  Types of Technical Report
  Business Plans
  
  - A Business Plan is a plan or proposal to start a new business or to expand an existing one.
  - It is aimed primarily at potential investors.
  - It should describe the proposed business, facts about the explored market and the competition, projected revenues, operation, and output of the proposed business.
  
  General characteristics of Technical
  Reports
  Graphics :
  - “A picture is worth a thousand words”.
  - A typical report that includes graphics can put across to the reader the most complex of operations.
  - Get in touch with a graphics illustrator or brainstorm for graphics for inclusion in your technical report.
  
  General characteristics of Technical
  Reports
  Factual detail :
  - The report should be very detailed and factual.
  - The point is to go into details which is what the specific audience is looking for.
  
  General characteristics of Technical
  Reports
  Information sources
  - The report should make use of information sources,
  - These may include books, articles, technical brochures, interviews, correspondences with experts.
  
  General characteristics of Technical
  Reports
  Documentation
  - When you use borrowed information in your technical report, be sure to cite your sources,
  - While documenting your sources, it is always necessary to do so using numbering system.
  
  General characteristics of Technical
  Reports
  - Realistic audience and situation
  - The report must be defined for a real or realistic group of readers who exist in a real, realistic situation,
  - You can afford to invent an audience and situation. The report needs to be addressed to somebody specific.
  
  General characteristics of Technical
  Reports
  Heading and Lists :
  - Reports should always used the format for headings and various kinds of lists
  
  General characteristics of Technical
  Reports
  Special format :
  - The technical report uses a format that includes covers, binding, title page, table of contents, list of figures, letters and appendixes.
  - These have to be prepared according to the set standard.
  
  General characteristics of Technical
  Reports
  Technical Content :
  - The Technical report should be designed in such a way that it should be easily understood.
  - You must write for the non-specialist.
  
  Checklist for Technical Report
  
  - Have you included all the required components in the required order, for
  example, transmittal letter, followed by title page, followed by figure list, and so
  on?
  
  Checklist for Technical Report
  - Have you addressed your report to a real or realistic audience that has a genuine
  need for your report?
  - Have you identified in the introduction what background the audience needs to
  read and understand your report?
  
  Checklist for Technical Report
  
  - Does your report accomplish its purpose? Is that purpose clearly stated
  in the introduction?
  - Does your report use information sources and have you properly documented them?
  
  Checklist for Technical Report
  
  - Does your report use the required format for headings.
  - Does your report use the required format for lists.
  
  Checklist for Technical Report
  
  - Does your report use graphics and tables? Does your report use the required format for graphics and tables.
  
  Checklist for Technical Report
  - Does every new section (which starts with a first-level heading) start on a new page?
  - Have you checked for widowed headings (headings that start at the very bottom of a
  page)? stacked headings (two or more consecutive headings without intervening
  text)? lone headings (a single heading within a section)? parallelism in the phrasing of headings?
  
  Checklist for Technical Report
  - Have you included an informative abstract in your report; is it positioned properly in relation to the other report components.
  - Specifically, does your informative abstract summarize the key facts and
  conclusions of your report rather than act as just another introduction or descriptive abstract?
  
  Checklist for Technical Report
  
  - Does the introduction of your report include the elements necessary in good
  introductions, such as audience, overview, purpose?
  - Have you avoided the problem of having too much background in the introduction,
  or having an introduction that is all background?
  
  Page Design
  
  Page design will include the following
  -aspects
  -Headings
  -Lists
  -Notices
  -Tables
  -Highlighting
  -Margin, Indentation and Alignment
  -Font and Color
  
  Guidelines for Headings
  
  - Design headings so that they clearly indicate their level.
  - Use Type size, type style, color, bold, italics, alignment in such a way that the
  level of the heading is obvious.
  - Use headings that describe the section they introduce,
  
  Guidelines for Headings
  - Make headings parallel in phrasing.
  - Parallelism sends readers important clues as to whether the section is similar in nature to the preceding ones.
  - Avoid lone headings.
  - Avoid stacked headings
  - Avoid the user of pronouns to refer to the headings. Eg. For a heading “Configuring the Software”, do not follow it with the sentence
  “This next phase…”.
  
  Guidelines for Headings
  
  - Consider the use of “run-in” headings for the lowest level of headings.
  
  Guidelines for Lists
  
  - Lists are useful tools for emphasizing important points, and enabling rapid
  scanning of text.
  - Use numbered lists for items that are in a required order or needs to be referred to by a number for future reference,
  - Use Bulleted lists for items in no required order.
  
  Guidelines for Lists
  
  - Introduces all lists with a lead-in. Don’t use headings as lead-ins to lists
  - Punctuate list items with a period only if they are complete sentences, or have some embedded dependent clauses.
  - Use either initial cap or lowercase on the first word of the list items. Follow
  consistency through out the list
  
  Guidelines for Lists
  
  
  - Avoid excessive use of lists of lists with too many items. 7 to 10 items is generally considered the maximum for lists.
  - If in a page, there is a requirement for 3 to 4 lists, interleave the lists with regular texts to break the monotony.
  
  Guidelines for Notices
  
  - Notices are special formatted texts to alert readers to potential problems.
  - Use a standard hierarchy of notices in which notices are more prominent and noticeable as they become more severe,
  
  Guidelines for Notices
  
  - A typical hierarchy includes the following Danger symbol – for situations that involve potential fatality
  - Warnings – for situations that involve damage to equipment or process,
  - Notes – for emphasis for points of exception.
  - In addition to telling the readers to do or not to do something, explain what will happen if they ignore the warning, under what conditions to make use of the statement, how to recover if the statements are ignored.
  
  Guidelines for Tables
  - Tables are like vertical lists, but more structured and formal.
  - Look for repeating groups of items in your text that you can format as tables,
  - Use a table title. Make the table title the top row of the table,
  - Use column and row headings to define the contents of the columns/ rows. Highlight the column and row headings too.
  
  Guidelines for Tables
  
  - Left align text columns and their headings,
  - Right-align or decimal align numerical data,
  - Put standard measure units in the column or row heading rather than with each item in the column or row.
  
  Guidelines for Highlighting
  
  - Software documentation typically uses a lot of highlighting.
  - Highlighting can be done by bold, italics, alternate fonts, caps, quotation marks, or anything that draws attention.
  - Establish a plan for use of highlighting, and apply it consistently,
  - Use highlighting for specific functional reasons.
  
  Guidelines for Highlighting
  
  - For a good technical document, use the following techniques for highlighting
  - Use italics for simple emphasis,
  - Use bold for commands, on-screen buttons, and menu options,
  - Use italics for variables (user defined words),
  - Use alternate fonts for text displayed on screen or text that users must type in,
  
  Guidelines for Highlighting
  - Use capitals for screen and field names,
  - Use Initial cap for key names,
  - For extended emphasis, use the notice format.
  
  Guidelines for Margins, Indentation
  and Alignment
  - Typically for web browser text content, it is always preferred to headline indent,
  leaving the text indented to the right.
  - It makes the headings stand out.
  - Another variation used is the headlines in a left column and the text in a right
  column.
  
  Guidelines for Font & Color
  - Use the most common fonts – some readers may not have the same font that
  you do,
  - Typical fonts used are Arial, Times New Roman and Courier New.
  - Be careful if you are using smaller fonts.
  - Verify whether it is visible on different type of machines and browsers.
  
  Guidelines for Font & Color
  - Use colors minimally (An accepted norm is to use the color for a heading (if it exists) for table titles, List titles and the tags for Notices.
  - Avoid unusual combinations of texts and colors. It should be visible. (purple or red text on a black background is horrible to read. Use black text on a white or gray
  background unless there is strong function reason for some other color combination.)
  
  Technical Writing approach
  -Audience analysis
  -Topic ideas
  -Brainstorming
  -Invention
  -Narrowing
  -Outlining
  -Libraries, documentation, cross-reference
  -Note-taking
  -Rough-drafting
  -Peer-review
  -Power revision (includes sentence level review, Weak verbs, redundant phrasing, Weak use of passive voice, subject-verb mismatch, sentence length)
  
  Weak verbs
  
  - Problem: The contribution of Quality Circles is mostly to areas of training and motivating people to produce higher quality work.
  
  - Revision: Quality Circles contribute to the training and the motivating of people to produce high quality work.
  
  Avoid piling of nouns
  - Problem: There is a growing awareness of organizational employee creative capacity.
  
  - Revision: Awareness of the creative capacity of employees in all
  organizations is growing.
  
  Redundant phrasing
  
  - At this point in time
  - Then In light of the fact that
  - Since, because During the time that Then
  - In this day and age Now, currently
  - With reference to the fact that
  - Concerning, about
  - In close proximity to Near, close, about
  
  Avoid weak expletives
  
  - Problem: When there is a very strong build-up at the front of the plane, it is what is known as a shock wave.
  
  - Revision: When a very strong build-up occurs at the front end of the plane, a shock wave occurs.
  
  Revise passive – voice sentences
  
  Passive: The papers will be graded according to the criteria stated in the syllabus. (Graded by whom though?)
  
  - Active: The teacher will grade the papers according to the criteria stated in the
  syllabus. (Oh! that guy...)
  
  Revise subject – verb mismatches
  
  - Problem: Consequently, the body is more coordinated and is less likely to commit mental mistakes.
  
  - Revision: Consequently, workers will be more coordinated and commit fewer mental errors.
  
  Sentence length problems
  
  - Problem: In order to understand how a solid, liquid or gas can be made to give off radiation in the form of a laser beam, one must
  understand some of the basic theory behind laser light.
  
  - Revision: A solid, liquid or gas can be made to give off radiation in the form of a laser beam. Understanding this process requires some
  knowledge about the basic theory behind laser light.
  
  Technical Writing
  
  - With proper planning and focus on the aspects of technical writing, we can
  present documents and manuals to our customers, our team which is clear, concise and easy to read.
  
  Thank you.