Re: document design: I don't know what I don't know
On 8/28/2012 5:34 PM, Becca wrote:
I am in a technical communication certificate program ... I'm not a
graphics designer, and not interested in the design of type faces, for
example, but I know I need to know more about specing type faces
beyond Arial and Times New Roman. the trouble is, I don't know what I
don't know - I'm not sure where to begin asking the questions, much
less finding answers.
So - if you were designing a 3-credit course in designing technical
documentation, what sorts of topics would you include?
Fonts
-----
I wouldn't put typefaces at the top of the list of topics, although it
is important in technical writing; just not necessarily the details of
typefaces. Reader preferences have certainly changed over the years for
various reasons and these preferences are necessary to understand.
For example, for some font philosophers serif fonts are thought to help
the reader follow the flow of the text and be easy on the eyes, while
sans serif fonts are thought to be more work. This is almost like saying
serifs are training wheels or crutches for readers. So readers with
challenged vision, poor reading skills, and new readers may benefit from
serif fonts and possibly larger font sizes.
College graduates who read daily, other people who read often,
especially those who read more electronic documents than printed
documents often prefer sans serif fonts. Popular fonts, like Arial and
Times Roman may be appealing to inexperienced readers, but annoying to
daily readers. Creative fonts are not appropriate for comprehensive
documents.
Printed documentation designs often must consider the cost of printing
and serif fonts tend to use more ink than sans serif fonts. These are
all considerations for fonts, but they can probably be handled in one
small section of a document design course.
Communication
-------------
The primary goal of technical writing and really the only important goal
is communication. Technical writing is about synthesizing complex
technology and processes as a singular subject matter and explaining
that subject matter to the audience in a language the audience will
understand and can accept, whether they like it or not.
A rudimentary technical writing course should emphasize communication to
simplify complex terms and concepts for the audience. A more advanced
course may want to include learning styles and the various forms of
publication for technical documentation. A successful, 3-unit document
design course should incorporate and build on using communication and
learning styles in document design.
In primary technical writing courses, students should learn to use
vocabulary to communicate complex concepts in simple term and students
should learn basic structures of grammar and documentation format. Like
the need to break documentation down with headings and clear paragraph
structure. Well-structured documentation focused on communicating
complex concepts in simple terms lends itself to a variety of
documentation designs.
Style
-----
Writing style is necessary in documentation and in document design.
Writers need to develop their own voice, while technical writers must
develop a "neutral" voice. Developing voice is a matter of developing
style and style are the rules and habits that control the writing. The
writer's voice should be a part of the document design. So if the voice
is a neutral voice designed for telecom user, then a slide show should
not have a circus theme and be designed for children.
Style guides are important and are often required in various
environments. There are style guides for nearly every industry and major
publisher. (http://en.wikipedia.org/wiki/Style_guide)Understanding the
role and availability of style guides should be in rudimentary technical
writing courses, but using style guides may be a part of document design
if it is not well-covered in other courses. If the writing follows a
particular style guide, then the document design should also follow the
rules of that style guide.
Some elements of style often raise controversy and should be discussed
in writing courses rather than design courses, like the serial comma
(necessary in legally-binding documentation, forbidden in journalism),
bulleted lists (whatever Bill Swallow says about that), how many fonts
and font sizes to use in a document (MS Word lies), spacing between
sentences and after a colon (one, unless you learned to type on a
typewriter and your inner voice shouts, "I'll give you my unnecessary
space when you pry it from my cold, dead hands!"), and anything else
that is fun to argue but really a waste of time for substantive
discussions, except for discussions about developing a style guide.
Visual Readability
------------------
Documents must have a visual appeal for people to want to read them.
While breaking documents apart with headings should be covered in
rudimentary writing courses, use of white space and the layout of
documents may sometimes be too involved for basic courses. If this
necessary piece of designing documents is not covered in the basic
courses, then it should be covered in a design course. There are many
other points of visual readability that people have already discussed
that may belong in basic courses or could belong in a design course,
depending on the courses your school already offers or requires.
Graphics
--------
Graphics are important and necessary in documentation. Using graphic
tools and designing graphics should be its own course, but a course in
document design should include how to use graphics in documentation to
support the needs of the documentation without hindering the reader.
Placement of graphics in the "real estate" of the document, such as the
printed page, web page, or presentation slide, requires balance between
the needs of the audience and the purpose of the document, and balance
within the document itself. For example, marketing documentation may
include more graphics than words in the real estate of the document,
while process documentation will include more words than graphics.
Documentation Types
-------------------
People generally understand the basic documentation type of a printed
document that is very much the same whether printed on paper or printed
on the screen; producing documents in this document type should be
second nature for technical writing students. Printed documents are also
the basis for other document types that technical writers choose from
and use according to audience and business needs. There are many types
of usually printed documents that technical writers produce.
* User guides
* Training documentation
* System manuals
* White papers
* Capital-raising documents, like feasibility study reports,
proposals, and business plans
* Release notes
* Policies and procedures
* Business process documents, like as-is, to-be, and re-engineering
* Reverse engineering documents when companies have let their
documentation slack for awhile, these are essentially "as-is"
documents with nowhere useful to start the documentation project
A 3-unit course of document design should study the basic document types
and some not-so-familiar document types. The basic document types that
most technical writers use in addition to basic printed documents follow.
* Web pages
* Slide Show Presentations
* One-page Help sheet, like printing instructions next to a printer or
overview of some business process
* Diagrams, while diagrams are often graphics within documents, they
do have applications as stand-alone documents
* Books
* Help
Some documentation may be its own "type," but not necessarily its own
document, yet it should get some discussion.
* Mouseover Help
* Callouts
* Labels, like for warnings and information
* Status Updates in social networking
* Text messages, like from global or general systems
Other document types that are not used quite as often, but perhaps
should get more attention, follow.
* Brochures
* Pamphlets
* Flyers
* Newsletters
* Press Releases
Some documentation goes beyond the scope of technical writing but should
be discussed as a possible direction for the student.
* Speeches
* Audio presentations
* Videos
* Advertising and Commercials
* Other media and multimedia
How to design documentation for different documentation types depends on
what information must be communicated, how much information must be
communicated to the audience, and how much real estate is available for
providing the written or graphical communication.
Becca, the list has given you a *lot* of information to build a
comprehensive independent study course. The challenge I think you may
face now is simplifying that information into something that can be just
a 3-unit course, rather than what is starting to look like 18 to 36
units of study.
Take a look at what the other technical writing courses are offering and
avoid duplication. Look at what non-technical writing courses are
offering and find a way to provide introductions and summaries to show
how the subject matter of those courses relates to technical writing.
For example, a graphics program can help a student produce graphics,
while a document design course will help a student use those graphics in
documents.
You are very ambitious to take on such a challenge as designing an
independent study course on technical document design. There are so many
types of technical writing documents and I never had a course to teach
me about all of this. The courses I took twent-<flurbally> years ago
typically focused on producing the content rather than developing the
form of the technical writing, with the exception of a brief overview of
maybe three to five documentation types.
Good luck!
Lauren
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.
Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://bit.ly/doc-to-help
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com
Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
Previous by Author:
RE: techwriting style vs press release
Next by Author:
"Commercial Off The Shelf" Manuals
Previous by Thread:
Chart of awful font choices
Next by Thread:
html/css question
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads