Table of Contents
Insider's Guide to Technical Writing Index
Return to Insider's Guide to Technical Writing, Technical Writing, Technical Writing Bibliography, Writing Bibliography, Writing, Writing Topics, Awesome Tech Writing
A
A4 pages 241
abbreviations 219
in style guide 218
Latin 61
plurals of 221
in translated content 257
accessibility, see assistive technology
accuracy
importance of 125
see also correct content
acronyms 214, 219
as part of a style guide 214
dictionaries 121
active voice 57–58
definition 295
Adobe products
Acrobat 149
Captivate 158
Flash 159
FrameMaker 147, 148, 153
Illustrator 153
Photoshop 153
RoboHelp 147, 158
Technical Communication Suite 147
Agile 109–111
advantages of 192
definition of 295
.ai file formats 151, 261
Ajax, definition of 295
APIs 77, 82
definition of 295
documentation for 99
apostrophe, proofreader mark 207
appendixes, as part of book 230
Apple Publications Style Guide 216
Application Programming Interface, see APIs
application, definition of 295
aptitude, for technical writing 7, 18
ascenders. definition of 295
ASCII, definition of 295
assistive technology
definition of 296
PDF compliance 86
audience
analysis of 85
audience, understanding 73–86
author comments, see comments
B
back matter, in a book 230–236
background, of technical writers 26
backlog 110
definition of 296
backward calendar 137
baseline, definition of 296
best practices 56
definition of 296
in technical writing 55–72
Best Practices Conference 291
bitmaps 150
definition of 296
body text 244, 246
bold type
for emphasis 60
proofreader mark for 207
when to use 86, 186
books 94
building 147
developing 147–150
pages of 240
single-sourcing from 146
templates for 239–249
tools for 28
boredom 281
brevity, in web content 51
bugs
in release notes 96, 97
in troubleshooting 98
trackers for 100
build
definition 296
including documentation in 141
build, including documentation in 208, 210
building a portfolio 30–32
bullet lists 59–60
in style guide 219
burnout 281
definition of 296
business expertise, using in the job-hunt 34
C
C, C++ 140
definition of 296
calendar, use of in scheduling 137
callouts 152
capitalization 220, 221
in bullet lists 220
proofreader mark 207
career path 284–285
lack of 280, 287
career, changing 33, 289
Cascading Style Sheets, see CSS
cautions 60
Center for Information-Management Development 291
center, proofreader mark 207
certification
Cisco 25
Project Management Professional (PMP) 20
STC 10, 36, 289
Certified Professional in Technical Communication 10, 36
change bars 193, 208
definition of 296
changes
being a catalyst for 15
career 284, 289
in priorities 6
in schedule 19, 277
changing jobs 287, 289
checklist, final 207–208
Chicago Manual of Style 216
.chm help file format 157
clarity, see clear writing
clear writing 18, 51–52, 56
close space, proofreader mark 207
code names, for products 52
college degrees
necessity of 26
suggested major 27, 28
colons 221
command line syntax
fonts for 244, 249
translating 259
command references 228
commas 68
inserting 207
serial 221
comments, in a draft 184, 208
completeness of content 48–49
computer-based training 83
conditional text 146
definition of 296
conferences
for technical writers 290, 316
presenting at 292
STC TechComm Summit 36–37
confidentiality 185
Confluence wiki application 156
consistency 52–54, 204
in style guide 54
consultants 271
definition of 296
consumer websites 51
content design books 310
content management 142
Content Management Strategies (conference) 291
content reuse 88–90
definition of 296
tools for 28
content sharing 29
context-sensitive
definition of 296
help 157
contractions 221
contractors
anticipating need for 129
definition of 271, 296
hiring 128–131
how to become one 273
where they work 272
control, taking 281
copyrights 226–227
definition of 297
Corel products
PaintShop Pro, image editing tool 153
Ventura 148
corporation, technical writer’s place in 6
correct content 46–47, 102, 125, 192
slightly modified in different files 88
correct word usage, in style guide 223
correcting mistakes after proofreading 206
cost of incorrect documentation 46
CPTC (Certified Professional in Technical Communication) 36
cross-functional, definition of 297
cross-platform, definition of 297
cross-references 48, 208
CSS 30, 140, 154
definition of 297
Cupertino effect 188
customer feedback, tracking 286
customer support representatives 83
customers 77
as users of documentation 78
of e-commerce sites 51
cutting corners 133
D
Darwin Information Typing Architecture, see DITA
deadlines, for reviewers 195
degrees
in technical communications 27
necessity of 26
suggested major 27, 28
delete, proofreader mark 207
delivery checklist 207–208
demonstrations 119
dependability 24
descenders definition of 297
design 239
design documents 101
definition of 297
desktop publishing tools 147
detail, attention to 19
developers 77, 82
documentation for 98
development process, about 109
Dia, diagramming tool 154
diagramming tools 154
dictionaries, online 317
difficult people, working with 279
discounts, student 29
DITA 143, 145
categories 180
definition of 297
using for translation 258
DITA North America Conference 291
DocBook 143, 145
definition of 297
documentation
definition of 4, 297
for internal audience 100
quality 125
documentation plans 112
definition of 297
domain expert, definition of 297
draft markers 185, 208
drafts
definition of 297
first 184, 186
sending out for review 193
sending out in small chunks 194 see also reviews
drilling down 183
drop-off 51
DTDs, definition of 297
DTP (desktop publishing) 147
due dates, for drafts 195
E
ease of use 49
ebooks 147, 149
definition of 297
e-commerce sites 51
editing 204–205
another’s work 205
images 152
your own work 204
educational discounts 29
distributing reviews by 196
shutting off 127
emergencies, creating to work faster 126
emphasis 60
end points 69
definition of 297
end user documentation 92
end users 77, 78
definition of 297
expert 79
novice 79
English language 76
.eps file formats 151, 261
ePub format for ebooks 149 see also ebooks
e-reader, see ebooks
error messages 93
error recovery 49
error-free content, see correct content
escalation path, definition of 298
expert users 79
external facing
definition of 298
documentation 141
extranet 210
definition of 298
F
Facebook 156
familiarity with product 116
FAQ 83
definition of 298
fast pace in high-tech environment 20
fast working 126
feedback
as part of usability 49
from customers 286
gathering 196
fields
changing 289
in which technical writers work 6
final checklist 207–208
Flesch-Kincaid reading index 65
flexibility, need for 19
flowcharts 28
flush, definition of 298
fonts 245, 248
bold 86, 186, 207
definition of 298
difference from typeface 246
in headings 248
in commands 249
monospaced 53, 249
onscreen 246
setting line length 244 see also typefaces
foreign words and phrases 61
formatting 125
for translation 259
FrameMaker, see Adobe
freelancers 271
freeze, definition of 298
freezing documentation 208–209
Frequently Asked Questions 83
definition of 298
future tense, avoiding 67
G
gaps, in a draft 184
gathering information 106
gender-neutral pronouns 61–62
George Orwell 67
gerunds
definition of 298
in bullet lists 59
getting started guides 101
Gilbane Content Management Conference 291
Gimp, image editing tool 153
globalization, see localization
glossaries 231
definition of 298
for translation 257
goals, of users 75
good, fast, or cheap 123
good-better-best lists 133–134
graphics 150–154
tools used for 28
grid 241
definition of 298
H
hard copy, definition of 298
HAT, see help authoring tools
help 94, 156
authoring tools 28, 147, 298
definition of 300
planning content for 181–183
heuristic evaluations 50
definition of 298
highlighting 60
high-tech work environments 6, 275
fast pace in 20
HLDD (high-level design documents) 101
hover help, see mouseover help
HTML 30, 140
definition of 299
editing 154
human factors, definition of 299
humor 62–63
hyphens 221
I
icons, for emphasis 60
illustrations 153, 238
tools used for 28
translating 261
image editing tools 153
image files, translation problems with 260
images 150–154
editing 152
imperative mood 63, 70
definition of 299
incorrect documentation, cost of 46
indent, proofreader mark 207
indexes 208, 231–236
informational interviews 39
definition of 299
insert space, proofreader mark 207
installation documentation 95
Intelligent Content Conference 291
internal product names 52
internally facing documentation 142
definition of 299
international audience, writing for 256 see also localization
international documentation, see localization
internships 27
gaining later in life 34
interviews 39
asking for job during 41
difficulty of obtaining 35
dressing for 41
telephone 39
thanking afterward 42
video 40
with subject matter experts 173
INTJ (Myers-Briggs type) 22
introductions, in books 229
italics
for emphasis 60
proofreader mark 207
J
Java 140
definition of 299
JavaScript, definition of 299
JIRA 100
definition of 299
job experience, need for 26
job levels, of technical writers 284
job shops 272
job-hunting websites 316
jobs
changing 287
starting new 164
K
Keirsey Temperament Sorter 22
knowledge bases 155
definition of 299
L
languages
expansion of 259
read by users 76
Latin abbreviations 61
LavaCon Conference 291
layers
definition of 299
in image files 151
leading 247
definition of 299
learning about the product 116
left/right pages 240
line illustrations 151
line length 243
linear form 147
LinkedIn 38
links 208
Linux, definition of 299
lists 126
preceding with colons 221
LLDD (low-level design documents) 101
localization 253–262
definition of 300
difference from translation 256
writing for 256
locator
definition of 300
lorem ipsum 247
definition of 300
lowercase, proofreader mark 207
M
MadCap Flare 147, 158
maintenance of documentation 166
management
books about 311
of Tech Pubs 285
marcomm 102
definition of 300
marker, definition of 300
marketing requirements documents 100
methodical approach to learning product 120
metrics 286
definition of 300
Microsoft Manual of Style 216
Microsoft products
PowerPoint 153, 159
SharePoint 210
Visio 154, 182
Word 148
milestones 114
definition of 300
mobile devices 140
monospaced fonts
definition of 300
monospaced typefaces 249
MoSCoW method 101
mouseover help 50, 157
definition of 300
moving to other company 287
MRDs 100
multitasking 20, 127
Myers-Briggs Type Indicator 22
N
names, of products 221
narrative form 147
NDAs (nondisclosure agreements) 288
negatives, avoiding 66
networking 35, 289–291
need for 26
on the web 38
websites 316
new job, starting 164
newbie experience, capturing 121
nondisclosure agreements (NDAs) 288
notes 60
keeping 47
novice users 79
numbers, style guidelines for 221
O
online help, see help
open source software, definition of 300
operations people 77, 82
organizations, for technical writers 316
Orwell, George 67
outdents 60
definition of 300
outlines 179–181, 188
filling in 184
out-of-the-box experience 80, 125, 148
definition of 300
outsourcing agencies 272
ownership, of what you write 288
P
pages
in a book 240
layout example 242
single-sided 240
sizes of 241
structure of 241
page-sensitive help 157
Paint.NET, image editing tool 153
paragraph, proofreader mark 207
parallel form, in lists 59
passive voice 57
definition of 301
how to recognize 57
when used 58
PDF Creator 149
PDFs 140, 147, 149, 159
definition of 301
peer editing 205
definition of 301
people management, books about 311
people, working with 21
periods, inserting 207
person (in grammar), definition of 301
personality types 22
personas 75
definition of 301
phone screen 39
photographs 153
placeholders 108, 184
definition of 301
Plain Language 66
planning
as part of document development 107
books about 310
documentation projects 112
single-sourcing projects 146
PMI (Project Management Institute) 20
PMP (Project Management Professional) 20
portfolios
building 30–32, 314
getting samples for 288
showing proprietary material in 288
PRD, see product requirements documents
present tense, writing in 66
presenting at conferences 292
printed documentation 148
when to provide 148
prioritizing 132
procedure guides 224
procedures 69–71
product knowledge, how to obtain 116
product managers
definition of 301
product names 221
product requirements documents 100
products, how to learn about 117–122
proficiency, expected of technical writers 9
programmers 82
programming languages 140
Project Management Institute 20
Project Management Professional credential 20
project scope 131
proofreading 206–207
marks 207
proprietary 185
definition of 301
proprietary information 288
PTC Arbortext 144
punctuation 221
Q
QA, definition of 301
qualifications
for a technical writer 4
technical ability 18
quality 125
of documentation 4
tracking 286
quality assurance 301
QuarkXpress 148
quick start guides 81, 101
definition of 301
R
ragged type 247
definition of 301
raster files 150
definition of 301
translating 260
Read Me First! A Style Guide for the Computer Industry 216
reading levels 52, 65
README 97
definition of 302
redoing documentation 109
redundant pairs
definition of 302
reference documentation 102 see also reference-based documentation
reference indexing marker 302
reference-based documentation 91 see also reference documentation
registered trademarks 222
release notes 96–97
reliability 24
requests for proposals (RFPs) 78
requirements documents 100, 172
definition of 302
responsibilities, of technical writers 10
resumes
avoiding typos in 33
formatting 32
how long hiring managers look at 32
writing effectively 32
reuse 28, 88–90
reviewers, choosing 191
reviews
consolidating feedback from 198
distributing in small chunks 194
email 196
mini 198
process 189–200 see also drafts
sending first draft out 193
tabletop 197
what reviewers can ignore 192
revising documentation 109, 164, 166, 202
revision control 142
revision section, in a manual 230
rewriting documentation 166
roadmaps
definition of 302
Rockley Group 291
rollover help 157
rule of seven, in procedures 71
run books 82
definition of 302
S
sales people, as users of documentation 78
sandbox 119
definition of 302
sans serif type
in headings 248
schedules
breaking down 126
calculating 134–136
creating 131–138
for translation 261–262
scope 131
scorecards 286
screen shots 151
definition of 302
translating 260
Scribus 148
scrum
as part of Agile 109
definition of 302
SDLC (software development lifecycle) 109
search engine optimization, definition of 302
second person 62, 67
definition of 302
Section 508 86
definition of 302
self-help 7, 83
definition of 302
sentence case
definition of 303
serial comma
definition of 303
serial commas 68, 221
serifs 245, 246, 249
definition of 303
servers, definition of 303
setting expectations 133
seven steps rule 71
SharePoint 210
sharing content, tools for 29
short sentences 52, 64
short words 52, 58, 64
short-term workers, see contractors
“should,” use of 69
sign-off 190, 209
simple writing 63–66
Simplified Technical English (STE) 65
single sourcing 140
single-sourcing 88–90, 155
definition of 303
planning 146
skills, expected of technical writers 9
social media 155
definition of 303
Society for Technical Communication, see STC
software
buying used 30
saving money on 29
software build, see build
Software User Assistance Conference 290
specifications 101
definition of 303
specs, see specifications
speed, improving 126
spell out, proofreader mark 207
spell-checking 33, 185, 187, 188, 205, 207
splash page
definition of 303
spreadsheets, for ongoing projects 286
sprints 109
definition of 303
SQL, definition of 303
stakeholders 48
definition of 303
STC 36, 290
presenting at 292
TechComm Summit 36–37
STE see Simplified Technical English
stet, proofreader mark 207, 303
structured authoring
definition of 303
structured content 140, 144, 147
definition of 303
student discounts 29
style guides 53, 164, 213–223, 307
backups 216
classics 216
contents of 214
creating your own 216–224
helping faster work 215
making mandatory 215
suggested contents of 218–223
styles
choosing “right” one 217
defining 216 see also style guides
subject matter experts 115, 173
definition of 304
meeting in person 175
Summit, STC 36–37
support representatives 77, 83
surrogate users 86
definition of 304
surveys 287
.svg 261
.svg file formats 261, 151
T
tables of contents 208, 227–228
checking document structure with 228
tabletop reviews 197
tags, in XML 143
taking over someone else’s project 165
task analysis 75
task-based approach to learning product 120
task-based documentation 90
TBS (to be supplied) 184
team player, being 24
TechComm Summit 36–37, 290
Technical Communication UK 291
technical communications degree 27
technical communicators, see technical writers
technical knowledge, importance of 18, 117
technical skills, enhancing 289
technical writers
alternative names for 5
aptitudes 7, 18
definition of 4
job levels 284
other names for 5
place in organization 6
qualifications of 4
typical workday of 10–15
where they work 6
TechSmith products
Camtasia 29, 94, 158
TechWhirl 38
TECHWR-L mailing list 38, 290
Tekom Conference 291
telephone screen 39
templates 178, 207, 238, 239–240
definition of 304
tense, definition of 304
testing documentation 201–202
thank-you email, after interview 42
third person, definition of 304
time to complete job, estimating 134–136
time to market 133
definition of 304
title case, definition of 304
title pages 226
to be supplied (TBS) 108, 184
Toastmasters International 292
tools 139–159
books about 309
for books 28
for content reuse 28
for flowcharts 28
for graphics 28
for help 28
for illustrating 28
required by employers 28–29
topic-oriented writing 89
definition of 304
tracking with spreadsheet 286
trademarks 217, 222
trainers 77, 82
training documentation 83, 102
training sessions, attending 85
translation 253–262
difference from localization 256
formatting problems with 259
glossaries 257
language expansion 259
of image files 260
of screen shots 260
process 255
scheduling 261–262
using DITA in 258
writing for 258–261 see also localization
translation company, assessing 254–255
translation memory 256, 257, 258
definition of 304
transpose, proofreader mark 207
triggers 69
definition of 304
troubleshooting 76, 98
definition of 304
documentation 97–98
tutorials 83, 93–159
tools for 29
Twitter 156
typefaces 244–247
bold 86, 186, 207
onscreen 246 see also fonts
types, of users 74
typographical conventions 229
typos, in resumes 33
U
U.S. Government Printing Office Style Manual 216
UA Europe 290
underlines, for emphasis 60
Unicode, definition of 304
UNIX, definition of 304
unnecessary words 65
eliminating 52
unstructured content 147
updating documentation 88, 165, 166
usability 49–113, 125
definition of 305
Usability Professionals’ Association (UPA) 291
use cases 90
definition of 305
user advocacy, by technical writer 15
user assistance, see help
user experience 49
definition of 305
user guides 92
user interface, definition of 305
user stories, definition of 305
user-centered design 50
definition of 305
user-friendly documentation 55
users
anticipating needs of 49
expert 79
goals 75
learning about 73–86
meeting 84
novice 79
observing 84
surrogate 86
types 74
when you cannot meet 85
who know more than the writer 74–77
writing for 50, 74–77
writing help for 183
UTF-8, definition of 305
V
vector files 151
definition of 305
translating 261
verifying, as part of document development 108
version control 142
video interviews 40
voice 57, 295
definition of 305
voiceovers 159
W
warnings 60
Waterfall 111–112
definition of 305
web content 51
tools used for 28
web servers, definition of 305
web services
definition of 305
web-based application 51
websites
about 313–318
creating own 291
WebWorks ePublisher 147
WFH, see working from home
white papers 102
definition of 305
white space 243
definition of 306
wikis 156, 210
definition of 306
“will,” avoiding use of 67
work for hire, definition of 306
workaround, definition of 306
workarounds 97
workday, typical 10–15
workflows 120
definition of 306
working faster 126
working from home 265–270
working with others 21
difficult people 279
writer’s block, battling 187
Writers UA 290
writing
ability for a technical writer 18
as part of document development 108
books about 308
for localization 256
for translation 258–261
websites 313
wrong font, proofreader mark 207
WYSIWYG 154
X
x-height 245
XMetal 144
XML 30, 140, 144, 147
about 143–145
definition of 306
schemas 143, 306
tags 143
Fair Use Sources
Writing: Cloud Monk's Books (Cloud Monk's Package Manager Book, DevOps for 20 Languages by Cloud Monk and Functional Programming Compare and Contrast 10 Languages by Cloud Monk), Cloud Monk Library, Cloud Monk, Technical Writing, Technical Writing Bibliography, Technical Writing Courses, Writing Tools (AWESOME DokuWiki, Leanpub, DokuWiki, Spell Checker, Grammar Checker - Grammarly, Mind Maps, Outlining), Technical Writing Glossary, Writing Topics, Awesome Writing, GitHub Writing. (navbar_writing)
© 1994 - 2024 Cloud Monk Losang Jinpa or Fair Use. Disclaimers
SYI LU SENG E MU CHYWE YE. NAN. WEI LA YE. WEI LA YE. SA WA HE.