# RootPrompt.org   Nothing but Unix.[Home] [Features] [Programming] [Mac OS X] [Search]


 Review: Spring Into Technical Writing - Great pastime while staying at cheap hotels

Spring Into Technical Writing for Engineers and Scientists published by Addison Wesley Professional is a great tutorial and reference for anyone who currently writes technical documents or needs to learn how.

The author Barry Rosenberg is a technical writer and instructor for Technology Exchange Company. He is the author of more than 30 programming manuals, including Addison-Wesley's Client/Server Computing for Technical Professionals: Concepts and Solutions and KornShell Programming Tutorial.

 (Submitted by Noel Tue Jul 19, 2005 )

  

Spring Into Technical Writing for Engineers and Scientist

By Barry J. Rosenberg

Review Copyright 2005 Noel Davis.

Spring Into Technical Writing for Engineers and Scientists published by Addison Wesley Professional is a great tutorial and reference for anyone who currently writes technical documents or needs to learn how. Any one can do it! Whether you are someone who writes for fun or a serious writer, you can always use skills to fine tune your technical writing abilities. Writing is a great pastime. If you travel, while staying in cheap hotels you can write using your lap top, or if you are stuck in an airport you can write help time pass. Regardless of who or why you are writing, you should give it a try, and read this article for tips!

The book is packed with good technical information all written in a clear and understandable manner. The chapters are laid out in a logical progression that takes the reader on a journey from planning the writing project through editing the finished project.

Sections that I found very useful included the chapters on lists, tables, and graphics. The descriptions on these topics explained when to put information in a table and when a list is more appropriate. The section on graphics strikingly pointed out the power of an image to add to your writing or distract from it.

This book is obviously created from years of background in writing about technical information. It will help a new writer who has been given the job of writing documentation and will also be of use to an experienced writer who wants to improve their writing.


Table of Contents
Preface.
I. PLANNING TO WRITE.
1. The Quest.
    Technical Writing Theorems
    Technical Writing Can Be Creative
    Tell 'Em
    The Value of Technical Communication to You
    Comparing Technical Writing to Engineering and Science
2. Audience.
    General Education Level
    Experience and Expertise
    Breadth of Audience
    Native Language
    Native Culture
    Audience Motivation
    Medium and the Message
    Becoming the Audience
    Summary of Audience
3. Documentation Plans.
    Document Specifications (Doc Specs)
    Doc Specs: Sample
    Documentation Project Plans
    Documentation Project Plan: Sample
    Summary of Documentation Specifications
II. WRITING: GENERAL PRINCIPLES.
4. Words.
    Jargon
    Consistency
    Verbs
    Adjectives and Adverbs
    Pronouns: He, She, and They
    Pronouns: You
    Pronouns: It and They
    Fluffy Phrases
    Commonly Confused Words
    Summary of Words
5. Sentences.
    Active Voice and Passive Voice
    Active Voice Is Better
    When Is Passive Voice Okay?
    Short = Sweet
    Causes of Long Sentences
    One Sentence = One Thought
    Parenthetical Clauses
    Summary of Sentences
6. Paragraphs and Sections.
    Sentence Transitions
    Paragraph Length
    Paragraph Transitions
    Sections
    Summary of Paragraphs and Sections
7. Lists.
    Bulleted Lists
    Elements in Bulleted Lists
    The Length of Each Element
    Numbered Lists
    Directions
    Introductions to Lists
    Parallel Lists
    Summary of Lists
8. Tables.
    Column Headers
    Units of Measure
    Arrangement of Columns and Rows
    Parallelism in Tables
    Amount of Text in Cells
    Rules
    Shading
    Captions
    Summary of Tables
9. Graphics
    Graphics
    Time Series
    Extra Detail in Online Graphics
    Before and After
    Callouts versus Embedded Text
    Graphics That Orient Readers
    Screenshots
    Color Blindness
    Block Diagrams
    Text That Supplements Figures
    Technical Photography
    Line Art Enhances Technical Photographs
    Big Picture First, Then Details
    Layout: Controlling Focus
    Layout: Keeping Eyes on the Page
    Layout: White Space
    Summary of Graphics
10. Professional Secrets.
    Explanations of Formula-Based Rules
    Examples
    Examples by Metaphor
    Examples for Programming Documentation
    Question-and-Answer Format
    Question-and-Answer Format Example
    In Other Words
    Tone
    Pace
    Footnotes and Other Digressions
    Beyond the Obvious
    Precision Descriptions
    The Hardest Part of Writing
    Summary of Professional Secrets
III. WRITING: SPECIFIC KINDS OF DOCUMENTS.
11. Manuals.
    Manual Style: Cookbooks
    Cookbook Example: Installing the Carambola Server
    Manual Style: Tutorials
    Tutorial Example: Getting Started with HTML
    Manual Style: Guides
    Guide Example: Creating HTML Headers
    Manual Style: Reference Manuals
    Reference Example: The pr1me Utility
    Manual Style: Nonverbal Manuals
    Online Help: Overview
    Online Help: Best Practices
    Online Help Examples
    Release Notes
    Release Notes Example: Carambola Web Server Version 3.7
    Prefaces
    Preface Example
    Glossaries
    Glossary Example: Tropical Weather Terms
    Tables of Contents
    Indexes
    Indexes: Providing Concise Entries
    Indexes: Permuting Terms
    Indexes: Providing Entries for Concepts
    Summary of Manuals
12. Web Sites.
    Plans
    Home Page: Specify Purpose and Audience
    Home Pages: Engage the Reader's Imagination
    Home Pages: Set the Tone
    Page Templates
    Navigators and Search Boxes
    Hyperlinks in Body Text
    Secondary Pages
    Text in Web Sites
    PDF versus HTML
    Frequently Asked Questions (FAQs)
    Summary of Web Sites
13. Proposals.
    The Proposal before the Proposal
    Adherence to the Proposal Template
    Proposal Element: Cover Letters
    Proposal Element: Biographies
    Proposal Element: Abstracts
    Proposal Element: Contingency Plans
    Proposals for Revolutionary Ideas
    Research Proposals
    Research Proposals: Significance Statements
    Research Proposals: Objectives and Hypotheses
    Research Proposals: Design and Methods
    Book Proposals
    Book Proposal: Example Marketing Section
    Business Plans
    Summary of Proposals
14. Internal Planning Documents.
    Business Proposals
    Business Proposal: Example
    High-Level Technical Specs
    High-Level Technical Spec Example
    Low-Level Technical Specs
    Low-Level Technical Spec Example
    Summary of Internal Planning Documents
15. Lab Reports.
    Abstract
    Introduction
    Materials
    Experimental Procedure
    Results
    Discussion
    Conclusion
    References
    Summary of Lab Reports
16. PowerPoint Presentations.
    Organizing a Presentation: The Big Picture
    The Number of Slides
    The Opening Moments of a Presentation
    Introductory Slides: The Traditional Approach
    Introductory Slides: An Alternate Approach
    Body Slides: Pace and Variety
    Mechanics: Fonts and Backgrounds
    Body Slides: Effective Lists
    Audience: The Theory of Relativity
    Graphics
    The Complexity of a Graphic
    Question-and-Answer Sessions
    Different Kinds of Learners
    PowerPoint Speech: The Basics
    PowerPoint Speech: Lessons from the Pros
    PowerPoint Speech: Overcoming Fear
    Summary of PowerPoint Presentations
17. E-Mail.
    The Essence of the E-Mail Problem
    Before Hitting the Send Button...
    After the First Miscommunication...
    Summary of E-Mail
IV. EDITING AND PRODUCING DOCUMENTS.
18. Editing and the Documentation Process.
    Editing: What Is It Really?
    Technical Editing a Peer's Work
    Technical Editing a Superior's Work
    Copyediting a Colleague's Document
    Copyediting Your Own Document
    Media for Technical Editing
    Bug-Tracking Systems
    A Process for Editing
    Beta Tests for Documentation
    Summary of Editing and the Documentation Process
19. Fonts and Typography.
    Serif and Sans-Serif Fonts
    Fixed-Width versus Variable-Width Fonts
    Serif and Sans-Serif in Hard Copy
    Serif and Sans-Serif in Soft Copy
    Font Height
    Italics and Boldface
    Consistency and Convention
    True-Type versus PostScript Fonts
    Summary of Fonts and Typography
20. Punctuation.
    Commas
    Dashes and Hyphens
    Semicolons
    Periods
    Colons
    Quotation Marks
Glossary.
Bibliography.
Index.
Buy from Amazon:

Buy from Barnes & Noble:


Technical Writing: For Engineers and Scientists
Technical Writing:
For Engineers and Scientists


Our content can be syndicated: Main page Mac Page

Copyright 1999-2005 Noel Davis. Noel also runs web sites about sailing and kayaking.
All trademarks are the property of their owners.
All articles are owned by their author