A style guide is vital for writers and editors when producing publications and other writing projects—but it’s not the whole story.
Many writers and editors swear by a style guide when organizing, editing and writing their publications. Well-known style guides include the Chicago Manual, the AP Stylebook and the Microsoft Manual of Style for Technical Publications. Many corporations adapt elements of these to produce their own, distinctive style guides. But does it do everything you need as you plan, create and manage a publication or help project?
What are publication guidelines?
The term “publication guidelines” is often used to describe submission guidelines for contributors to a magazine or technical journal. I’m using the term in a wider sense: guidelines that cover any topic related to the publication that doesn’t fit in a style guide.
Often editors create a style guide to determine content and format in publications. A style guide can and should be part of publication guidelines, since a style guide is a set of stylistic guidelines for a publication. Publication guidelines, on the other hand, can be a bigger, wider-ranging document. But some are not.
What you include in these can vary widely. The publication guidelines published by the Virginia Highlands Community College and Delaware Valley College include topics like planning publications, logo requirements for the organization’s identity, and web design and development guidelines, among others. VHCC’s equal opportunity employment and accessibility statements give notice that the college complies with federal law in those areas.
The Journal of Applied Communications, for members of the Association for Communication Excellence (ACE), publishes guidelines for contributors. These are fairly typical of publications that seek technical or scientific manuscripts from writers, in that they include formatting guidelines, organization requirements (such as an abstract) and the publication agreement. The journal Molecular and Cellular Proteomics offers highly detailed technical guidelines to help researchers publish research manuscripts.
Want to get your paper rejected by the Association for Computing Machinery’s Special Interest Group on Graphics and Interactive Techniques? They offer tips on that as well as their guidelines! Funny, but useful for the writers.
Why write publication guidelines?
Publication guidelines can save time, money and hassles for writers and editors over the long term. They can help future contributors and others taking over, or updating a publication–especially if the new writers don’t have expertise in help authoring, publication management or other editorial tasks. They are especially helpful when contractors know they are going to pass along a project to an in-house documentation team—or, probably a worse situation, to the developers. They are invaluable to contributors if the project must be turned over before it’s finished.
They save money over the long run because editors and writers don’t have to reinvent the wheel and spend extra time duplicating research.
Ideally, these guidelines should cover many types of publications. Usually only minor elements, especially those related to software-specific issue, would need much change from one type of publication to another. They can apply to employee publications like newsletters; online product help guides and manuals; websites; marketing publications like emailed postcards, and brochures and other publications mandated by an organization.
Elements of publication guidelines
Publication guidelines contain much more information than what fits within the parameters of a style guide. They should include a style guide (or several, as needed), but also carry information that can help writers and editors manage any kind of publication imaginable.
Publication guidelines may include:
· Style and usage guides
· Planning and organization guides
· Help with the software and related procedures that are not well documented in the software help files
· Help with software-related procedures like backing up the project
· Mechanical issues, like formatting required in MS Word or HTML source documents
· Notes on templates and other mechanical essentials
· Lists of reference sources, like dictionaries, encyclopedias, technical websites, etc.
· Documentation of project contributor names, their contributions
· Documentation of any and all project help resources, including emails from support as well as resources found in books and on websites.
· Documentation of project file locations, if not obvious from the project software
· Other pertinent information like the EEOC, accessibility and corporate ID requirements noted above
The main point is to include as much information as you believe contributors need to do a good job with their contributions.
Publication guidelines can be as comprehensive as a budget, time, attention and energy allow. It may be best to err on the side of too much information; but that depends on the skill and education level of the writer or documentation team that will take over a project.
How can publication guidelines help?
I developed publication guidelines for NuStep in order to provide a framework to help future contributors and administrators of an online training and reference project after my assignment there ends. It’s aimed at those not familiar with the project, who are also novices with help authoring tools. The staff who will take over have varying levels of writing and editing expertise, including some technical writing. However, none has expertise with modern help authoring tools, and their skill level with managing publications is unknown.
The guidelines also contain general instructions on procedures related to using, in my case, Doc-To-Help, the software used to build the guide.
How do I start a publication guideline project?
For a good start on planning and organizing publication guidelines, write a very short mission and specific goals—and state them at the beginning of the guidelines.
Next, develop a tight outline based on those goals.
Here is the mission and goals for my project as noted in the publication guidelines. Many of the goals are quoted or adapted from Jean Hollis Weber’s excellent Technical Editors’ Eyrie, a website that provides many excellent resources, including an overview on planning an online help project:
Mission
“Make the online guide easy to read and use.”
Goals
· To make the online guide consistent and easy to navigate, read and understand
· To make the job of its editors, writers and other contributors easier by providing a reference source
· To inform new writers and editors of existing style and presentation decisions and solutions
· To improve consistency within and among documents, especially when more than one writer is involved or when a document will be translated
· To remove the need to reinvent the wheel for every new project, and document who contributed what to help future contributors
· Establish standard style guidelines to make the user/reader’s experience easy and clear
· Document and explain the use of standard styles and formatting in the template
· To remind the writer of style decisions for each project, when one writer works on several projects that have different style requirements
· To serve as part of the specifications for the deliverables, in the event this project is outsourced
· To define which style issues are negotiable and which are not
· To help with new users of [your software] and those unfamiliar with help authoring tools or web design applications in general
· To help plan, organize and schedule the work involved in producing and updating the guide
· To introduce usability testing to those unfamiliar it
A working outline
1) How to produce the online training & reference guide
a) Mission & goals
b) Publication guidelines outline
2) Planning guide
a) To do list
b) Tracking documents
3) Contributors’ guidelines
a) Social rules for creating a style guide
b) Editorial conventions
c) English usage
d) Ways to present information – best practices
e) Research – talk first to potential readers and technical (subject matter) experts
4) Editorial style and conventions
5) Formatting standards
6) Build and maintain the guide
a) Software – Doc-To-Help
b) Get started with the software
c) Help and support resources
d) About the template
i) Template purpose
ii) Find the template
iii) Apply template
e) Back up the template
f) Contribute to the guide
i) Writing & editing process
ii) Track progress
g) Build the guide
i) General instructions
h) Provide access to the guide
i) Maintain the guide
i) Update the guide
ii) Maintain the publication guidelines
j) Back up the guide
7) Reference sources
a) Reference sources
i) Style guides
ii) Dictionaries
(a) English
(b) Medical/technical
(c) Other languages
iii) Thesauri
iv) Encyclopedias
v) Quotations
b) Online non-reference resources
i) Email lists, discussion groups
ii) Technical websites and other resources
(a) Freeware & shareware software download sites
8 ) Website usability testing
9) Whodunit – publication principals and contributors
10) Technical notes and procedures
a) Procedures and emailed help from software support
11) Glossary
The bottom line
Writers and editors need a plan and guidelines for projects and publications of all kinds. A style guide is helpful, but comprehensive publication guidelines—documentation of the documentation—are immensely more helpful, and save money and headaches in the long run.
# # #
