Understanding Writing

Writing guidelines

Topic status automatically displays here - do not remove.

Bookmark me!Bookmark this topic  Print me!Print this topic

This topic provides guidance for the writer faced with the task of preparing material for publication—from concept to delivery. These guidelines are primarily designed for technical writers and are focused on their particular aspect towards writing. However, if you're not a full-time writer or not technical, don't let that put you off. Much of what is discussed is also appropriate to part-time writers and writers in non-technical positions, so for those still interested, these guidelines should be read in that light, extracting the information appropriate to your requirements and circumstances.

Traditionally in the publication process, the roles of authors, illustrators, graphic designers, editors, screen-based publishers, indexers, and printers have remained quite separate and distinct.

However, with the relatively recent advent of desktop publishing software programs, the widespread adoption and use of personal computers, and the advanced functionality of readily available desktop printers, these roles have become less distinct.

Nowadays, it is not uncommon for individuals to perform all the roles previously ascribed as separate occupations. They are now performed as separate tasks in the same occupation, commonly referred to as 'Technical Writer', 'Technical Communicator', 'Information Architect', 'Knowledge Worker', or even depending on the subject matter being written about, as 'Business Analyst', amongst other things.

Professional Technical Writers can provide detailed advice on the latest best practices in writing, editing, design and production. They make it part of their job to keep up-to-date on current developments and regularly assess tools and methodologies. They attend technical writer conferences, and monitor writing and tool lists as appropriate to their current work related interests and needs.

Technical writers come from all walks of life, quite often having a technical background in one or more of the fields of engineering, electronics, manufacturing, military, computer sciences, or more recently, networking and communications.

Often experienced people from those backgrounds had to perform some type of writing as part of their job to meet those business needs.

Some have evolved to become full-time writers as a career change, and brought with them vast and varied experience.

Other writers have a less technical background and write more generally than technically, relying upon subject matter experts (SME) to provide technical accuracy and checking.

No matter which type of writer you are, all types perform more publishing tasks than just writing the text. There is the need for providing appropriate illustrations and graphics, determining what information to present, the order and amount of information to present, and the best method to provide that information to the audience.

Primary consideration for the audience and what they're trying to achieve from the communication, should drive the purpose, content, style and presentation medium of the communication.

The needs and expectations of the audience must be considered if they are expected to be able to read, understand and use the information in the way the writer intends.

An assessment of the potential readership will greatly help in choosing the most suitable scope and structure for the communication, set its language and tone, its design, and its format.

These considerations are all part of the preliminary planning that underlies successful publications. Poor planning can result in a publication costing far more than envisaged, in terms of rework (and of damage to the reputation of those involved).

  1. The first step in creating a communication—any communication—is to know your audience.

  2. The second step is to plan the publication.
  3. The third step is to create and manage the publication.

Back to Top

Know your audience

Readers today are confronted with a plethora of information from which they must sort out what they want and need to know. The importance of focusing on the audience's needs when planning, structuring, writing, designing and editing a publication cannot be understated.

A careful assessment of the potential readership of the publication is vital for clear and effective communication. You cannot write effectively for someone without knowing a little bit about them. Better yet, the more you know about them, the easier will be your task of writing for them.

Ideally, you should know your audience well enough to be able to create user profiles for your publications, detailing: user age range, education level, reading style, requirements, and interests. User profiles are very useful at every stage of publication development, as they can always be used to determine whether something is right or not for the user. Always test your matter-of-concern in the communication against your user profiles for the communication.

Only after you have profiled your audience, can you accurately decide on the scope of information they'll require. You should:

These considerations will provide important influences on the choice of the communication's content, structure, design style and method of publication (paper-based, screen-based, or both).

These considerations will also help in matching the size, organization and emphasis of the document with the reader's interests. For example, they will suggest the amount of background material that should be included and whether extensive explanations and a glossary might be necessary. The design style and the number and type of illustrations used will also be influenced by this assessment.

Decisions about vocabulary (which could range from the colloquial to specialist terminology) should also be aligned with the perceived educational and cultural backgrounds of the expected readers and their familiarity with the subject.

Back to Top

Planning the publication

The publication plan defines and records the reasons for publishing the document. This statement of purpose will then serve as the focus for decisions about the document's format, structure, writing style, design and production.

Guidelines should be drawn up to cover the writing, editing, design and screen-based publishing tasks. Establishing an integrated approach at the beginning saves time and expense. Start by compiling the writing and editing guidelines for the publication. Include an outline of contents which shows all the elements planned for the publication. Professional design input at this stage can dramatically improve the document's readability and readers' comprehension of the information presented.

Particular structural and design factors associated with access, on-screen reading and navigability must be taken into account when developing the guidelines for a screen-based publication. The time spent by authors and information designers in assessing and tailoring the communication to the medium and its intended uses, translates into time saved for readers. Look-up time is a crucial factor when structuring information for retrieval and usability.

The aim in developing the publication guidelines is to produce a cohesive, amalgamated set of specifications and templates for all aspects of the document. This comprehensive (and continually updated) resource provides all members of the publishing team with a detailed understanding of the overall approach and is an essential tool for achieving consistency throughout a publication.

If the benefits to be gained from both print and electronic publishing options are to be maximized, the distinguishing characteristics of each option need to be exploited. This means, structuring, writing, designing and producing documents to match readers' expectations appropriate for each medium. For example, a printed work will likely have a table of contents, an index and page numbering, whereas an electronic version may not necessarily have those elements, yet contain hyperlinks and a search facility.

Documents that are well planned and executed tend to satisfy their users better, and for longer. The aim of publication management is to ensure that the project is completed on time, within the budget, and to the specified level of quality. This is a discipline that requires careful planning, and a commitment to the management plan by all contributors to the project. Good communications and regular monitoring and reporting of progress are essential.

'Usability testing' of the writing process has traditionally been done by an editor (as the 'advocate for readers'), to ensure that the concepts, structure, language and presentation will match readers' expectations. For an electronic publication, testing for accessibility and navigability must be built into the publishing schedule. Before release, the document should also be rigorously tested, to check that it functions effectively in a variety of possible user environments.

The project designer should draw up the design specifications in close consultation with the client and other members of the publishing team. Incorporated in the design specifications (where relevant) will be page and screen layout instructions for margins, indents, fonts and line spacing; specifications for the heading hierarchy; details for headers and footers and any footnotes; and instructions for the design and placement of identification information, navigation icons and menus. Specifications for illustrations and tables should take account of the need for visual consistency and information comparisons, as well as defining the style for titles, legends, labels, internal table headings, and so on. Instructions relating to any relevant client identity schemes and colors should also be included.

Many of the design specifications can be applied through electronic tools such as typographic style sheets, master pages and layout templates that can be used to achieve consistency during the writing and editing processes.

Back to Top

Planning for usability

Generally, considerably less material at a readable size will be visible in a screen window than on most traditionally sized printed pages. Readers of on-screen documents must scroll through material, and this means they must remember information they can no longer see. To avoid hampering reading efficiency by too much scrolling back and forth, documents intended for on-screen use are often divided into 'chunks' that can be viewed independently.

Other aids for screen readers include the use of frequent headings, navigation bars displaying the current location within the document schema, hyperlinks to previous, next, and related subjects, sidebars for additional information, search facilities, and the placement of important material in a non-scrolling section (where it always remains visible).

Effective, consistent navigation systems are essential in maintaining readers' awareness of where they are in an electronic document, and where they might best go next. Generally, a minimum number of steps should be required to find the information, while keeping the navigation path transparently logical. Also, icons must be clear and consistent, and the range and structure of the information must be obvious and logically accessible through straightforward heading and overview systems.

These findings should be supported by the writing and editing guidelines.

Back to Top

See Also

Lotech Solutions' Tips, Tricks, and Procedures

Back to Top