The document discusses technical communications and provides definitions and concepts. It outlines the technical aspects of technical writing including objectives like communicating technical messages effectively and simplifying complexity. It also covers the communications aspect, such as ensuring clarity and relevance for the intended audience. Additionally, it compares technical writing to other literature and discusses considerations for form and structure. Finally, it addresses usability goals and design paradigms as well as potential pitfalls to avoid in technical communications.
2. Agenda
Definitions and concepts
The technical part
The communications aspect
Tech writing vs. other types of literature
Form and structure
Usability and other user-centric
communication practices
3. Agenda
Definitions and concepts
The technical part
The communications aspect
Tech writing vs. other types of literature
Form and structure
Usability and other user-centric communication practices
4. Definitions and concepts
Documentation: n. The multiple kilograms of macerated,
pounded, steamed, bleached, and pressed trees that
accompany most modern software or hardware products.
(Jargon Files)
By three methods we may learn technical writing: First by
education, which is noblest; second by methodology,
which is easiest; and third by planting your butt in a chair
and pecking out the damn document, which is the
bitterest. (Andrew Plato)
5. Definitions and concepts
The real technology -- behind all our other technologies --
is language. It actually creates the world our
consciousness lives in. (Andrei Codrescu)
Making the simple complicated is commonplace; making
the complicated simple, awesomely simple, that's
creativity. (Charles Mingus)
6. Technical communication is a collaborative process of
conveying useable information about a specific
technology to an intended audience.
Definitions and concepts
7. Agenda
Definitions and concepts
The technical part
The communications aspect
Tech writing vs. other types of literature
Form and structure
Usability and other user-centric communication practices
8. The technical part
The problem with allowing the engineers who create a
program also write its Help and Tutorials is that you get
people who cannot write, writing Help for people who do
not need help. (Mark Rector)
Manuals just slow you down and make you feel stupid.
The directions are too slow, too detailed, and use too
much abstract, arcane or academic language -- like boot
up instead of turn on the red switch in the back. (Neil
Fiore)
9. The technical part: objectives of
technical communication
Communicate a message of a technical nature
effectively, with emphasis on understanding technology.
Create documentation that is helpful, accurate,
comprehensible, and accessible to the intended
audience.
Share or transfer knowledge
Instruct and educate
Simplify the complex
Warn about effect to well-being of others
10. The technical part: tools of technical
communicators
Thorough understanding of the technology being
documented and of the audience using it
Expertise on major word publishing software: Adobe
FrameMaker, MS-Word, Acrobat PDF
Applied knowledge of online Help development tools:
RoboHelp, Doc-To-Help, Macromedia Flash, Captivate
Basic knowledge of usability and visual literacy
Grammar/editing skills
11. The technical part
Rule 1 of writing software for non-technical users is this: if
they have to read documentation to use it you designed it
wrong. (Eric Raymond)
Reading computer manuals without the hardware is as
frustrating as reading sex manuals without the software.
(Arthur C Clarke)
Documentation is the castor oil of programming. (Gerald
Weinberg)
Voluminous documentation is part of the problem, not part
of the solution. (Tom DeMarco)
12. Agenda
Definitions and concepts
The technical part
The communications aspect
Tech writing vs. other types of literature
Form and structure
Usability and other user-centric communication practices
13. The communications aspect
Never express yourself more clearly than you are able to
think. (Niels Bohr)
Make everything as simple as possible, but not simpler.
(Albert Einstein)
Present to inform, not to impress; if you inform, you will
impress. (Frederick P Brooks)
I once used the word obsolete in a headline, only to
discover that 43 percent of housewives had no idea what it
meant. (David Ogilvy)
14. The communications aspect:
what to relay
Clarity (know your vision, purpose, scope, goals,
audience, benefits, limitations)
Refinements (edit, test, and get feedback)
Relevance and timeliness
Usability
Hierarchy of importance
Logic of activities/tasks to perform
Technical accuracy and completeness
15. The communications aspect
Put it before them briefly so they will read it, clearly so
they will appreciate it, picturesquely so they will remember
it, and above all, accurately so they will be guided by its
light. (Joseph Pulitzer)
16. Agenda
Definitions and concepts
The technical part
The communications aspect
Tech writing vs. other types of literature
Form and structure
Usability and other user-centric communication practices
17. Versus other literature: common themes
and variations
Common concerns: clarity, conciseness and audience
Inverted pyramid
Measured, measurable: no free text
Usability and use of illustrations
Focus on technical accuracy and completeness
18. Versus other literature: common themes and
variations
It's no coincidence that the most popular PC books go by
names like "Windows for Dummies". They don't sell books
like "Oldsmobiles for Idiots" or "A Foul-Up's Guide to
Fords". (Patrick L Anderson)
Technical documentation is like sex; when it's good, it's
very, very good, and when it's bad, it's better than nothing.
(Dick Brandon)
19. Agenda
Definitions and concepts
The technical part
The communications aspect
Tech writing vs. other types of literature
Form and structure
Usability and other user-centric communication practices
20. Form and structure
User: n. The word computer professionals use when they
mean "idiot." (Dave Barry)
35. Agenda
Definitions and concepts
The technical part
The communications aspect
Tech writing vs. other types of literature
Form and structure
Usability and other user-centric
communication practices
36. Usability
Usability is a term used to denote the ease with which
people can employ a particular tool or other human-made
object in order to achieve a particular goal.
37. Usability: goals
More efficient to use—it takes less time to accomplish a
particular task
Easier to learn—operation can be learned by observing
the object
More satisfying to use
39. Usability: design paradigms
In the user-centered design paradigm, the product is
designed with its intended users in mind at all times. In the
user-driven or participatory design paradigm, some of the
users become actual or de facto members of the design
team.
40. Usability: pitfalls
The term user friendly is often used as a synonym for
usable, though it may also refer to accessibility. The use
of terms user friendly and user friendliness should be
avoided, as there are no widely accepted definitions for
them, and they are thus often used without much
substance.
41. Usability: pitfalls
Here are terms to beware of:
Fool-proof or idiot-proof (oh, you mean you think your
customers are fools or idiots?)
User-friendly (which usually means to hold users by the
hand and force them to do things one step at a time, in
prescribed order, whether they like it or not)
Intuitive (which in actuality means so automatic it is not
conscious. Those who use the term forget that almost
everything we call intuitive, such as walking or using a
pencil took years of practice. (Don Norman)
42. Usability: pitfalls
Software suppliers are trying to make their software
packages more user-friendly. Their best approach, so far,
has been to take all the old brochures, and stamp the
words, user-friendly on the cover. (Bill Gates)
44. International Council for Technical Communication
Society for Technical Communication
Institute of Scientific and Technical Communicators (UK-based)
Technical Communicators Association of New Zealand (NZ-based)
Usability Professionals' Association of New Zealand (NZ-based)
Tekom (Germany-based)
TECOM Swiss Society for Technical Communication (Swiss-based)
STIC Dutch Society for Technical Information and Communication
(Netherlands-based)
Association for Computing Machinery's Special Interest Group on the Design
of Communication (USA-based)
Finnish Technical Communications Society (Finland-based)
Conseil des Rédacteurs Technique (France-based)
Associations
Resources and References
49. Thank you: questions, please
And remember: Together, an effectively designed product and
document makes the world a better place for us.
Editor's Notes
Information is useable if the intended audience is able to perform an action or make a decision based on its contents.
Technical communicators often work collaboratively to create products (deliverables) for various media, including paper, video, and the Internet.
Deliverables include user manuals, technical manuals, product specifications, process and procedure manuals, training, business papers, reports, etc.
Usability can also refer to the methods of measuring usability and the study of the principles behind an object's perceived efficiency or elegance.
In human-computer interaction and computer science, usability usually refers to the elegance and clarity with which the interaction with a computer program or a web site is designed.
The term is also used often in the context of products like consumer electronics, or in the areas of communication, and knowledge transfer objects (such as a cookbook, a document or online help).
It can also refer to the efficient design of mechanical objects such as a door handle or a hammer.
Information is useable if the intended audience is able to perform an action or make a decision based on its contents.
Technical communicators often work collaboratively to create products (deliverables) for various media, including paper, video, and the Internet.
Deliverables include user manuals, technical manuals, product specifications, process and procedure manuals, training, business papers, reports, etc.