Business and Technical Writing
Serif fonts are sometimes called
"Roman."
Sans serif fonts are sometimes called
"grotesque" or "Gothic."
In Acrobat, editors can add
"sticky notes" that mimic those you might actually place on a paper. They can also cross out, highlight, and underline, and allow you to use a set of standard graphics tools or mark freehand with a tool that mimics a pencil.
subject matter expert
A person who is an expert on a given topic or skill. should be consulted in any technical document
document type definition (DTD)
A set of rules contained in a simple text file that defines the structure, syntax and vocabulary as it relates to tags and attributes for a corresponding document.
trim size
The final size of a printed piece after being cut from the sheet of paper that it was printed on.
header row
The first row of the table that is formatted differently and should be repeated for tables that continue beyond one page.
style guides for newspaper writing
Associated Press Stylebook The New York Times Manual of Style and Usage BBC News Styleguide
things to keep in mind while writing a document to be translated
Avoid contractions such as "can't" or "don't" as they cause confusion for non-English speakers. Avoid references that are hard to translate such as slang, irony, idioms, and metaphors. Use culturally neutral examples. Be aware that units of measure, time, and dates are specified differently in different countries. Give appropriate contact information including international calling codes. Edit your work before translation. Grammatical errors will cause difficulties for the translators. Be aware that your work may expand up to 25% after translation. This may affect the cost of printing, binding, and have an impact on a document's layout.
Playwright George Bernard Shaw
England and America are two countries separated by a common language
endnotes
If all of the citations in a book are collected and appear at the end of the document
Have you ever wondered why many publications use "web site" and not "website"
The Chicago Manual of Style requires "web site"
overrides
While it may be tempting to use your word processor's formatting tools rather than character styles to apply character formatting, do not do so unless you have no alternative. Such manually applied formats are a "sin" in the technical writing world.
Software for Review and Collaboration
While paper edits still happen and knowledge of the basic marks can be helpful, in many settings they have been superseded by software tools that facilitate collaboration and review
Proustian sentences
Works of creative writing might contain long, complex sentences
flow chart
a diagram that represents the steps in an algorithm or process
Many printed texts use
a sans-serif face for headings, a serif face for body text, and a monospaced font for certain types of examples
Time, difficulty/skill level, cost, and other needs usually preface
a specialized tutorial. It is also useful to include some objectives or goals at the beginning of a specialized tutorial in order to set the reader's expectations
International Organization for Standardization (ISO) 690
a standard for bibliographic referencing in documents of all sorts including electronic documents. Microsoft Word supports this standard as one of its bibliographic options
technical writing is
a sub-genre of business writing. It is writing that documents all aspects of the use of complex products.
Under U.S. law, copyright protection is automatic from the moment
a work is created in tangible form
break down your document into
coherent topics that can be described in no more than a screen full of text
Help files are a
common documentation project for any new product release
Kate Turabian's A Manual of Style for Writers of Term Papers, Theses, and Dissertations
common general style reference for students
Web-based documentation helps
companies keep files cross-referenced and up to date
subtask
component within a larger task
Presentation writing must be
concise and to the point. Bullet points are usually in parallel form and sometimes contractions (abbreviated sentences) are permitted
choosing a paper
consider how long the final printed product needs to remain useful
Using slide templates is important for
consistency, but designers should avoid the unprofessional default options
Front matter
consisting of everything that appears before the book's body
draft
an attempt to get down on paper what is known.
Back matter
consisting of everything that follows the body
body
consisting of the book's main content
A widely quoted passage from Robert Binghurst's The Elements of Typographic Style, calls for
anywhere from 45 to 75 characters per line of printed text with a 66-character line considered "ideal." These numbers are for a single-column page set in a serif typeface at standard text size
Information that does not belong in any of a book's chapters, but that must appear within a given volume, sometimes ends up as an
appendix
unordered list, aka bullet list
contains items that have no fixed ordering or which do not represent steps to be carried out in sequence
Duplex printing may not be
appropriate for very formal business documents, such as business plans, proposals, or resumes
Graphs, also known as line charts
are a good means of showing trends
U.S works published before Jan. 1, 1923
are in the public domain
What goes on a slide
at a minimum a good slide should include a topic title and information that elucidates that topic.
Understand the topic or product thoroughly before
attempting to write about it
When planning a document
begin with the why it's needed then move on to what information must be included
preface
brief description of a book's contents
Basic rules of English composition still apply in
business and technical writing, along with some special considerations
Data points are connected
by lines or smoothened, producing a picture of changes in a value over time
Wikipedia's article history and reference list
can help you verify information
When writing about software
capitalize the same way the software does, unless this conflicts with house style. If Adobe says "Pen tool," don't call it the "pen Tool."`
Both quoted and paraphrased sources should be
cited in the main text and listed in the endnotes or bibliography.
Use the simplest possible image to
convey the message in a business or technical document
Copy editing is limited to
corrections of grammar and other presentational errors
Reviewers of documents should look for
correctness and completeness. Other reviewers may focus on organization, readability, grammatical correctness, and adherence to company style guidelines.
Page numbers that appear at the bottom of a page are part of a
corresponding area known as the footer
step
corresponds to a single action in a procedure.
Designers commonly use business writing to
create client proposals and communications, and use technical writing to produce brand manuals, training documents, and tutorials.
Most data representations do not need to be
created from scratch
Keep your references organized from day one so
creating your end notes or bibliography will be a snap
headings and subheadings
divide the document into small chunks, allows the reader to skim
Use right alignment for
easy reading of numerical data, or use decimal stops to align decimal data.
developmental edit
edit done early in the writing process, the editor helps the writer to plan the document's organization, content, and presentation
copy edit
editorial review that is done just before a work is sent to be printed or published
ordering principle
essential to making the table useful
Style guides can be
for general writing or for specialized fields
The Bluebook: A Uniform System of Citation or ALWD Citation Manual
for legal documents
Online content must
get straight to the point
XML documents contain text and markup, but
have nothing to say about their final appearance when published
Any common or dangerous pitfalls must be
highlighted in user guides
Some word processors can handle multi-column layouts, but
if you are using a complex newspaper-type layout you might consider authoring your text in a word processor and laying it out in Adobe InDesign.
The data representation tools
in presentation software packages like PowerPoint can really enhance a presentation
Use the standard set of flow chart symbols, preferably
in software used for charting
Place the most important written content
in the upper left of a web page
annotated bibliography
includes a summary of a source's content, an evaluation of its usefulness, or both
note
information of interest that does not flow with the main body of text or that merits special attention
Creating a well-crafted custom template
is a big time investment. It is most worthwhile if the design can be reused for many similar documents
OneNote
is a note taking app that assists you in entering, saving, organizing, searching, and using notes.
ream
is a quantity of sheets of paper of the same size and quality. While in the past, the number of sheets in a ream have varied, today's ream has been standardized at 500 sheets
The goal of a user guide
is generally to help a user establish a basic level of confidence with a product
the navigation and structure of the help files
is just as important as the writing of the content itself
Extensible markup language (XML)
is not a single markup system but a language that can be used to specify a multiplicity of markup systems customized to specific needs.
Tables need a title if the content of the table
is not obvious or if you will be cross referencing the table from elsewhere in the document
XML code looks like HTML, but
its tags are defined by the DTD or by the user.
Marcel Proust
known for his long sentences
Copy edits typically do not
lead to changes in content or organization
Slides must be carefully copyedited
like any other business document. Typos can be distracting and undermine the presentation
Printed materials are more
likely to be read word for word than electronic materials, which are more likely to be skimmed
use an ordered list
list the steps in a procedure where each step is associated with an action that must be performed in sequence.
Slideshows are helpful tools for
live presentations, and some might say essential for delivering any complex information
caution
mandatory information that can save the reader of the document from making a serious mistake that may lead, in the worst case, to equipment damage or personal injury
Use a standard text string (like the letters TK) to
mark sections where you need to do more thinking of research before you can write.
Business writing consists of
memos, letters, emails, reports, proposals, and other documents written in support of running a business big or small.
You may not use a trademark in a
misleading way
numerical values may be more easily read when presented in a
monospaced font
index
most common form of back matter, an alternate means by which readers can locate specific information of interest without wading through an entire book
Some schematics can be more abstract while others
must be more technical and created to scale
In a technical book
names are almost always used is a means of identifying the chapter's content so that a reader can easily skip to the chapter in question or skip over it
proportional-width fonts
narrow letters such as the "i" have a smaller width than wide letters such as the "m."
When illustrating a step-by-step procedure
numbers, arrows, enlargements, callouts, and other graphic features can really help communicate the required information
Copyrights
protect works of authorship (as opposed to patents which protect inventions or discoveries)
trademark
protects words, phrases, symbols, or designs identifying the source of the goods or services of one party and distinguishing them from those of others
tip
provides non-essential information that does not fit into the main flow of the text
Front matter may require
separate pagination from the body of a document
reference
sets out to provide complete information about all aspects of a product
Use good contrast between
shading colors and type colors for easy reading
keep sentences as
short and straight-forward as the content allows
Bar charts are a good means of
showing observations that vary over time
parallelism
similarity of structure in a pair or series of related words, phrases, or clauses
flow of control
the movement of the process through the chart
Page numbers that appear at the top of the page are part of
the page header.
acknowledgements page
the place where all those who contributed to the writing of a book can receive credit
Only use images when
they are necessary for illustrating the written content
The first time you use a term in a given text
use the full name followed by the abbreviation or acronym in parentheses. Subsequent references can then use the abbreviation or acronym alone. An exception to this rule is when the abbreviation or acronym is so commonplace that it does not need any explanation.
Adobe Acrobat
used to facilitate collaborative writing and review.
technical manuals
viewed as corporate publications rather than individual efforts, they seldom list an author
Charts offer a more
vivid and visual means of presenting data that might otherwise be presented in tabular form
most widely used monitor resolution is currently
1280x768 or higher.
It is believed that reading is
25% slower on screen than in print
template
A document that contains formatting, styles, and sample text that you can use to create new documents.
style guide
A manual that contains standards for the design and writing of documents.
before you begin writing
Always check to see if your company already uses a specific style guide
five business and technical writing essentials:
Be on target Be clear Be concise Be accurate Be polite
Page margins
Blank space that is set around the edges of the page
side heads
Headings that appear on the same line as body text
business or technical setting, citation doesn't just help you create your own document and give others due credit
It also helps you back up your writing to the big-wigs. Citing accurate, valid sources firms up the validity of your own writing and the points you are making with your documents
Use a callout on a busy graphic like a screenshot
It can help the reader understand where to look
When consulting an expert
Learn what you can from written and other sources before seeking out the expert for help. Prepare a list of questions in advance. Consider providing your list to the interviewee ahead of time. Consider whether a face-to-face meeting is best or if your questions might be answered just as well via email. Take good notes. You don't want to have to ask the same questions over and over again. Enlist the most important experts as reviewers for your work. Be unfailingly polite
Bookends
Mac app which promises to simplify information collection, annotation, and citation in various word processing apps.
Archival paper
Paper that is acid-free and has a quality lifetime of about 100 years or longer.
paraphrasing
Putting into words the ideas or feelings you have perceived from the message
What is fair use
Section 107 of U.S. copyright law lists certain purposes for which reproduction of a copyrighted work is allowable. These include such uses as criticism, comments, news reports, teaching, scholarship, and research
Do a quick "Find" in your finish document for any
TKs you forgot to fill in
cross references
Technical manuals commonly make reference to material that is located elsewhere in the current document or in a related document
localization
The process of taking a document or product created for one language and culture and translating it to another language or culture
a specialized tutorial assumes
a certain level of skill
William Strunk, Jr.'s The Elements of Style
a classic reference useful to the general public and many genres of writing. It is strongest on rules of usage, word usage, and what it calls "principles of composition." "Use the active voice, and begin each paragraph with a topic sentence."
fixed-width or monospaced font
all of the characters are set at a uniform width
Technical writers need
all of the skills of business writers plus an aptitude for presenting complex technical material to both technical and non-technical audiences.
Values with a variable number of decimal places must be
decimal-aligned
schematic drawing
depiction of a complex system that gives a visual explanation of how the system works
EndNote
designed to manage research, references, images, and PDFs and creates bibliographies within all of the major word processing applications
process of writing a business document
determine the audience plan the document refine your plan draft your document submit draft for review revise your work work with an editor
Markup
extra information that goes beyond a document's readable content
Business and technical documents typically demand
fact, not opinion
Curve fitting is a mathematical technique for
finding the curve that best fits a series of data points, rather than using a rough connection of points with lines
Citations have two parts
first is generally a superscripted number that appears in text at the point requiring the citation second part is the actual citation information.
The first step in writing a user guide is to
focus on the basic tasks a user must learn
Paragraphs should be
focused and limited in length
duplex printing
printing to both sides of the paper (if your printer has this feature)
summary
of the main ideas of a text
Technical materials
often provide additional header or footer information to give readers a quick means of grasping the context of the page they are viewing.
Page numbers are never placed
on the inner edge of a bound document or book.
procedure
ordered set of steps that accomplishes a subtask
Tables are best used to
organize data that lends itself to presentation in labeled rows and columns
When data points reflect conditions over a large geographic area
overlaying information on a map provides an easy way to give the big picture without having to list thousands of data points in a hard-to-grasp tabular format
Pie charts are the best choice for showing
parts of a whole
reading aloud will help you to
perceive awkward phrasings or other problems in a text.
A key first task with any appliance might be
plugging it in and turning it on. Don't take even the simplest task for granted!
Use a reputable almanac for
quick access to population stats, key historical dates, and more
Communicate the purpose of your document as
quickly and succinctly as possible
random access
refers to the ability of a reader to open a book at any page and start reading
callout uses a line to
relate a piece of text to a specific part of a diagram. Callouts can be especially helpful when an image is "busy"
organizational chart
schematic view of the organization's hierarchy that includes the names and titles of position holders
half title page
second title page, Legal notices including copyright, trademark notices, and the International Standard Book Number (ISBN), if applicable, go here
University of Chicago Press, The Chicago Manual of Style
standard reference for book writers, addresses a wide variety of document types including magazines, newsletters, corporate reports, proposals, electronic publications, web sites, and other non-book or non-print documents.
Any step-by-step instructions must have definite
starting and ending points.
Acknowledging the source of copyrighted material is not a
substitute for obtaining permission to use the work
Specialized tutorials are used to
teach very specific tasks, such as how to create a special effect in Photoshop or how to stain your kitchen cabinets
On typewriters
the Pica typeface had 10 characters per inch while Elite had 12
Information-carrying words
those words that must be understood to carry out the action described in a sentence - keywords or action words
Journalists and book writers use the abbreviation TK to mean
to come
line drawing
two-dimensional drawing that uses only lines with additional detail such as shading
Titles and header rows help readers quickly
understand tabular data
The ISBN is a
unique 13-digit numeric identifier used in commercial books along with a barcode for identification
Equal margins on all sides can be problematic
when a printed work is destined to be bound
Anything printed on paper made from wood-based pulp
will yellow and deteriorate over time. Exposure to light and heat accelerate that process
FrameMaker
word processor, commonly used in large technical writing projects, allows for both a site dictionary and a user dictionary to supplement the standard dictionary
Nix the sarcasm in
written documents. It may not translate as well in writing as it does in person
By giving someone a PDF version of your work
you allow someone who may or may not have your authoring tool to read your file in a version that is a faithful facsimile of the one you created.
If you are the sole user of a template
you can augment its style sheet if you find it necessary
by determining who is going to read the document
you can determine the tone, the level of detail, the terminology you employ
Sketch different methods of data representation to help
you decide the best one for the job
By using a well-designed template
you free yourself to think more about what you are trying to say and less about the page layout and typesetting aspects of what you are writing
If you are working at a large corporation
your job will be to modify boilerplate text drawn up by corporate counsel