The Quick and Easy Guide to
Electronic documentation, on-line media, "soft" documents, e-communications
all refer to the same thing: information designed for and distributed via
technology. Sometimes electronic documents are merely on-line versions
of paper documents. More often, however, electronic documents are specifically
designed for the technology used to distribute them. This customization
is usually required for optimal effectiveness and access to the information.
Types of Electronic Documents
These formats take the place of paper communications (letters, memos, etc.)
and some verbal communications (phone, recorded messages, meetings). Just
like the traditional methods they replace, they tend to be brief and focus
on a specific function or goal.
FAX (Paper or electronic documents sent and received electronically over
E-mail (Correspondence and files sent and received electronically over
Bulletin Board/Discussion Group (Asynchronous, threaded e-mail.)
Chat Rooms (Synchronous/Real Time discussions on-line.)
Video Conferencing (Synchronized phone & video over data lines.)
These documents take the place of paper reference materials and are usually
distributed with a product (software) or via Intranet/Internet.
They may be electronic duplicates of paper documents or may be designed
specifically for electronic use.
On-line Help Files (Instructions and reference material packaged with software,
usually accessed via pull-down menus or hypertext.)
On-line Documentation (Complete manuals, reference guides or specifications
designed for on-line use.)
Acrobat Documents (Documents created in Acrobat and accessed via Reader.
Files may be accessed via e-mail or intranet/internet, and may be printed
as designed. Cross-platform format. )
E-Books (Complete documents - fiction or nonfiction- accessed with an e-book
reader. Platform specific.)
These documents are interactive, using hyperlinks, on-line forms and various
script formats to provide a dynamic interface for the user. In other words,
the document gives the user control over how the document is "read". These
documents may include embedded media such as audio and video. Hypermedia
is usually accessed via Intranet/Internet. Intranet
refers to a closed network utilizing web browser access. Internet,
or World Wide Web, refers to an open network consisting of interconnected
smaller networks, accessed with web browsers.
Web Documents (Hypertext documents accessed directly via intranet/internet
using a web browser.)
Multimedia (Video, audio, animation and other presentation files embedded
into or downloaded from web documents. Acrobat, Quicktime and PowerPoint
files all may be designed as or within hypertext documents.)
Web Applications (Various databases and applications, such as search engines
and java applets, embedded or accessed from web documents. Protocols included
HTTP, FTP, GOPHER, TELNET and direct download from primary servers.)
Electronic vs. Paper Documentation
There are a number of significant differences between electronic documents
and paper documents. These differences influence how each type of document
is designed, delivered, and used. As a writer or a user of electronic documents,
you should be aware of these differences.
*Cost varies depending on initial investment in equipment and tools,
and on training staff to use the technology.
||"Open"; Dynamic; Interconnected; Non-liner; Dependent on Technology;
Multimedia; Cost Effective*.
||"Closed"; Static; Cross-referenced: Linear; Independent of Technology;
"Flat" Media (Text, Graphics); Cost Prohibitive*.
||"Immediate"; Cost Effective*; Upgrade Possible; User Controlled; Dependent
||Delayed; Cost Prohibitive*; Replacement rather than Upgrade; Sender
Controlled; Independent of Technology.
||User Controlled; Targeted (Task Specific); Scanned; Interactive; Dependent
||Writer Controlled; Comprehensive (Task & Background); Read for
Detail; Passive; Independent of Technology..
The most important of these differences is the shift to an open, dynamic
document controlled by the user and the reliance on technology for electronic
Designing Electronic Documents
Like most forms of writing, design of electronic documents should begin
with analysis of the purpose of the document and the audience's needs and
expectations. What do you wish to communicate? Who is the audience? What
are their goals for using the document? How will readers access and use
the document? Does the audience have restrictions on access and use? Only
after considering purpose and audience can technique be determined.
Tips for Designing Electronic Documents
For a further discussion of design issues, and a great example of a well
designed electronic document, see Andrew Mundi's Principles
of Graphic Design.
Organize around a relational design. Your document should include
interconnections both within the document and, perhaps, outside of the
document. This will create a "3-D" or "Deep" document, allowing for user
choice and non-linear use. Try to consider various ways the audience may
want to use your document. Include multimedia if functional and reasonable.
Develop multiple "paths" within the document. "Paths" are patterns
of use within the document utilizing hyperlinks, active menus and other
tools for navigation. Remember to include return paths to the main page(s)
or menus. You may also want to provide links to referenced documents.
Limit both text and graphics. You will need to balance the required
information with brevity and ease of use. Avoid dense text and layout that
requires much scrolling. Avoid unnecessary or large graphics (which will
affect download time.) Also, consider the variation of equipment, e.g.,
moniter size, video and audio cards, software versions, etc., that may
affect the audience's use of your document.
Use multiple methods to communicate your information. Given the
user control of your document, providing multiple methods of viewing/using
your document helps ensure effective delivery. Provide content in more
than one format. Combining an on-line format with a downloadable version
may be one solution
Think "Usability" when designing your document. Again, consider
ease of use for the audience. Download time, easy navigation, clear and
simple user instructions for document use will not only help the user,
it may ensure that the user looks at your document. (If it's too hard to
find or use, the user will give up!)
Include communications links. Most users appreciate a way to connect
to a person, via e-mail or phone, included as part of the documentation.
You may also want to link to other peripheral documents, such as a corporate
web site or sales materials.
Think like a user; translate for the developer. It is the writer's
job to ensure that the product makes sense to the user. Often this means
coordinating documentation changes with developers. It may even mean advocating
changes of the product or process.
Written By: George Knox © 1999