Re: document design: I don't know what I don't know

Subject: Re: document design: I don't know what I don't know
From: Lauren <lauren -at- writeco -dot- net>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 29 Aug 2012 13:35:40 -0700

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?

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.

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.

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. ( 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 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
* Email
* 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!


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.


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 for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @


document design: I don't know what I don't know: From: Becca

Previous by Author: Re: is there a word - for typing the wrong homophone ?
Next by Author: Re: How to archive an Exchange/Outlook e-mail list that you don't own?
Previous by Thread: Re: document design: I don't know what I don't know
Next by Thread: Re: document design: I don't know what I don't know

What this post helpful? Share it with friends and colleagues:

Sponsored Ads