Transwiki:Technical writing for the Web

Technical writing refers to the type of writing wherein technical information is made accessible to non-specialist audiences. The World Wide Web has spawned conditions that call for technical writers to build new types of skills, particularly those which can aid users to locate, synthesize, and evaluate information.

Technical writing for the Web is different from technical writing for print, as:


 * Web reading is 25% slower than reading in print
 * Web medium users expect mobility on the content page
 * Web pages compete with many other sites for attention
 * Users keep searching for the best page for their topic
 * Users want the information they are seeking in a very short time
 * Navigation through the information in a web is in a unique, nonlinear path

Technical writers now need to groom web-oriented skills in making many choices involving technical, aesthetic, and usability aspects. This book aims to help you develop these skills.

Technical writers working with print media are the gatekeepers for product information. They carefully organize product documentation, online help, and other user assistance for their readers. Compare this to the chaos of the web, where content is splattered across blogs, forums, wikis, and the like with little or no organizational scheme.

Illustrative Example
For example, a technical writer may get involved in writing instruction manuals, help resources, and promotional material. Also, they will be required to write for printed books and manual, online help documentation, and web sites. Hence, they need to adapt their writing styles to different media, whether it is print or online environment.

The difference in these writing tasks raise the question on what approaches to writing should be used when writing for different media - particularly when comparing writing for the web as against print.

History
Some historical facts on web as a writing medium
 * 1964 - Marshall McLuhan published Understanding Media, proclaiming that electronic communication media will soon turn the world into a “global village”
 * 1965 - Ted Nelson coined the terms “hypertext” and “hypermedia” to describe a model of non-sequential writing and accessing information, stressing the connections among ideas
 * 1986 - American National Standards Institute (ANSI) released Standard Generalized Markup Language (SGML), which became the basis of several subset markup languages, including HTML
 * 1987 - Phase of desktop publishing and page layout software like Venture Publisher, Interleaf, FrameMaker, and Aldus PagMaker
 * 1999 - eXtensible Markup Language XML evolved from HTML

Brevity of content
Web writers need to write no more than 50% of what they would write for print. “A writer has about 10 seconds on the web to make her point, from the time the user first clicks the link,” says online documentation specialist and technical writing instructor Freda Salatino.

Organizing content for users
Web writers need to understand site architecture and navigation. Navigation is a term to describe the movement of users through online information. “The user jumps to a topic and reads it, considers what has been learned, and jumps to another topic to read some more and jump again. Each jump takes the user closer to the answer to his or her question.”. A well organized online content will need only one or two jumps to bring the user to the answer sought.

Aiding scanning and browsing
Most online users scan the screen in front of them, visually searching for recognizable information. After getting oriented to their visual environment, they search for answers to their questions. Users browse (explore without a definite goal) when they are unsure of their question and the type of answer they are seeking.

Whether user is certain of his goal or not, an online author should make information accessible by clearly defining the path ahead. Web writers have to write for scanability by providing highly structured content, with aspects like :
 * Multilevel headings
 * Bulleted lists
 * Highlighting and emphasis
 * Topic sentences in every paragraph

Ease in accessing information
Web user can become disoriented as the underlying structure of online document is not visible. Providing consistent functional and visual elements together with navigation aids, like table of contents with hyperlinks, will make the user comfortable with the online environment.

Consistency
In discussing consistency for web pages, the Yale Manual for Web design advises: “Users need predictability and structure, with clear functional and graphic continuity between the various components and subsections of your web site”. Consistent use of functional elements allows the reader to recognize the structure and concentrate on the information goal rather than the means to reach there.

Navigation aids
Navigation aids will help online readers to get to their information more efficiently. Like table of contents in a paper manual, online readers need a list of links they can click to reach a topic. Further a site map can provide more detailed list, equivalent to an index in Books. Also navigation keys with labels, telling what action will happen on the page when clicking the label, will help readers to navigate documents better.

Chunking
Chunking (dividing information into small self-contained information units) is essential for online writers. Information Units are pieces of information packaged in any format: Each chunk should just describe a single topic and should contain enough information to be useful to the reader. Also different levels of information should be presented with short summarizing chunks, with links leading to detailed information. This will allow web users to only access information of their interest. Also, since readers on the web may arrive at different pages of their web sites, each page should work as an independent segment.
 * Text
 * Graphics
 * Video clips
 * Hypermedia

Authoring languages
HTML is the standard markup language used for web documentation. The content generated using HTML can be viewed in any Internet browser running on any computer operating system. XML may soon become the preferred online authoring language due to greater flexibility it offers over HTML.

Intercultural
The global audience for web materials creates a need for intercultural communication. Technical writers need to write content for the comprehension by a broad international audience, who might be anyone anywhere.

Ethics on the Web
Technical writing for the web, with its potential for wide public distribution of information, poses new and increasing constraints, regulations, and prohibitions in terms of use and distribution of information. Certain web accessible technical information is blocked by federal agencies for “safeguarding our national security”. Organizations like OMB watch (Office of Management and Budget who oversees federal agencies like EPA and FERC) track the removal of information from public websites. Simple declarative statements, such as “Hamburgers are high in fat” could violate food liberal laws in certain states. Borrowing digital images and text or even hyperlinking to an online article could constitute digital copyright infringement.