h1

Publication guidelines – sample mission, goals and outline

April 30, 2010

Sample mission and goals

Below are the mission and goals, as well as a sample outline, for an online sales training and reference project I developed for NuStep, Inc. in 2007-2008. These were included in the publication guidelines I wrote to help guide and develop the project.

Many of the goals are quoted or adapted from Jean Hollis Weber’s excellent Technical Editors’ Eyrie, which offers excellent resources. One of the key resources I found most helpful is an overview on planning an online help project.

Feel free to borrow from this outline. My goal is to help writers and editors, as I’ve been helped by many others.

If you do use the information, please also link to or refer to my website, timmantyla.wordpress.com.

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

Sample Outline for Publication Guidelines

1) How to produce an 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

h1

How can I help improve your communications?

September 13, 2009

I can serve your business by providing communications services with the following benefits:

Save you money

  • Develop, write, edit and manage publications to effectively communicate to your audiences–employees, customers, suppliers
  • Use simple, clear language to improve marketing, technical, web, training and other communications
  • Use single sourcing, wikis, blogs and other technologies to streamline communications and gain more customers
  • Help employees better understand training and technical documents
  • Save your company employee training costs and downtime
  • Analyze and organize your overall communication strategy

Boost sales and profits

  • Turn more website visitors into paying customers
  • Help customers clearly understand how your services and products benefit them by simplifying marketing copy
  • Boost web traffic by optimizing copy for search engines
  • Use company blogs to put you at the top of Google searches

Improve your business image

  • Drive customers to a website that “speaks their language”
  • Reflect your business professionally
  • Coordinate your communications with styles that fit within your brand guidelines

Increase customer & employee satisfaction

  • Improve readability of training materials and documentation
  • Improve website readability
  • Clarify and simplify technical terms
  • Improve marketing collateral readability

Encourage innovation with new ways to communicate

  • Build online help, wikis, blogs and other modern communication methods that cut costs, leverage and retain employee knowledge and speed up comprehension and access to information
  • Develop cost-saving knowledge bases by researching and documenting the company’s employee “knowlege bank”

Contact me

Ready to go? Want to find out more about how I can help?

Email me at tim -dot- mantyla – at – gmail – dot – com

h1

Creativity relies on many mental abilities

June 22, 2009

The more I think about creativity, the more it looks like my ideas about creativity have been stereotyped and limited.

For one thing, creativity doesn’t work all by itself. No mental ability works in a bubble, though we may think of them that way to more easily make sense of them.

For example, how could someone create anything without a vast reserve of memories to draw on? That’s not to mention visualization or imagination abilities. You have to be able to choose what to create, and those choices require memories of similar things to the thing being created.

And visualization itself requires memory. How could you make a mental picture of something unless you had a reservoir of many things and how they appear?

Painters who create a new work make choices about how it looks. They pull up memories of colors and how they look when mixed, the effects of various sizes and types of brushes and the way something looks on various media. Other skills include planning, organizing and the ability to focus on one subject for a long period of time.

Translating visual, verbal, aural or tactile ideas into physical media, as all artists do, requires a whole set of mental abilities to control body movement.

The abilities to control our bodies can be finely honed with practice, but we learn them automatically when we are children–without any memory of how it happened.

Have you ever tried to feel or analyze how your hand and arm move to pick up a glass? I can’t do it. It’s an invisible process that I have no access to. Bodily control is so essential to our lives that we don’t have ways to mentally interrupt or analyze it. We “will” the movement, and presto! We move!

It’s really quite magical and invisible–yet we all make myriad intricate movements every day. It’s so integrated into our ability to function that we take it for granted.

Another example: how could someone create a product without analytical skills, like those used to determine the usefulness of the product? When Gideo Sundback designed the zipper in 1913, the inventor/engineer must have first systematically compared and evaluated other clothing fasteners, then decided that something else could work better. In fact, he improved upon a zipper-like design called a “clasp locker.”

This creative act also required memory, critical reasoning, design skills, evaluative abilities and other skills. Emotions, including frustration over the limitations of buttons and hooks, could have driven the inventor’s desire to create the zipper.

When someone does something “creative,” it’s not only creative. It could be analytical as well. A creative act may require intuition, evaluation, comparison, critical reasoning, memory, visualization, or any other mental function alone or in combination with others.

The other thing I’ve noticed about mental activity is that it’s often hard to separate one activity from another, because they work so well together. Clearly they are separate skills, but the mind or brain’s abilities work together seamlessly–so effortlessly and rapidly, in fact–that we can’t possibly analyze every process that’s going on at the time it’s happening. (Well, I have to speak for myself on this. Maybe Stephen Hawking could do it.) Retrospection is neccessary to figure out what we’ve been doing during retrospection!

These observations bring up a question that has dogged humanity since recorded history: What could have created something as complex as the human mind?

It also brings up a question that confounds researchers and has created entire branches of philosophy: How could such amazing abilities be housed in something as small as the brain?

I don’t have answers, but Emerson Pugh, an influential IBM executive, captured the essence of the problem with a humorous twist:

If the human mind was simple enough to understand, we’d be too simple to understand it.

h1

Some mental abilities increase as we age

May 30, 2009

According to a Wall Street Journal article, “The Upside of Aging,” our mental abilities keep growing as we age.

American culture celebrates youth and many human abilities that decline with age. But contrary to prevalent beliefs, some mental functions actually increase in some areas while decreasing in others.

The aging brain is subject to a dreary litany of changes. It shrinks, Swiss cheese-like holes grow, connections between neurons become sparser, blood flow and oxygen supply fall. That leads to trouble with short-term memory and rapidly switching attention, among other problems. And that’s in a healthy brain.

But it’s not all doom and gloom. An emerging body of research shows that a surprising array of mental functions hold up well into old age, while others actually get better. Vocabulary improves, as do other verbal abilities such as facility with synonyms and antonyms. Older brains are packed with more so-called …

Speed of response times and reflexes decrease, according to the Journal article. But wisdom–a previously unquantifiable set of abilities–increases, says new research.

That’s because we develop “action templates” for experiences that we can apply to similar experiences. Younger minds don’t have enough experiences to develop templates as seasoned as those of older people.

These templates may be the foundations of what we call wisdom.

Sharp Brains, a website devoted to mental improvement, notes:

In our “Exercising Our Brains” Classes, we typically explain how some areas typically improve as we age, such as self-regulation, emotional functioning and Wisdom (which means moving from Problem solving to Pattern recognition), whereas other typically decline: effortful problem-solving for novel situations, processing speed, memory, attention and mental imagery.

Of course, this runs against my own experience: I knew far more at age 16 than I’ll ever know again. I certainly knew more than anybody else then.

But maybe my memory is just slipping…and I’ve merely forgotten most of it?

h1

Why blog?

July 22, 2008

Benefits of blogging

Blogging helps writers in many ways. These include:

  • igniting creativity
  • capturing ideas
  • good writing practice
  • promoting your product or service
  • improving your health

Blog posts can be anything you like

I love to blog. But so many of life’s necessities and projects vacuum time away from other fun stuff–and that includes blogging.

There’s a way to do it, though, that won’t turn your blogging into a full-time job. With a blog, you don’t have to fit every item into a preset format like you would with another kind of article, news item, think piece or essay.

Certainly it’s helpful to your target audience when you stick to a specific topic. But within that topic, you have almost free reign.

This is both heaven and hell for a writer. On the negative side, you could become a gushing Word Monster with overly long posts. The constraints of publication guidelines often demand cuts in content that you may not like, but which improve the writing. Discipline streamlines the work.

On the other hand, freedom can invigorate you. Writing exactly what you want to write is the editorial equivalent of soaking in a steaming bath.

Blogs can be notepads, forums, magazines–or whatever

Try this: If you have just a thought or two, use a blog as a notepad for an outline–or just to throw it out on the random winds of the Internet.

Opening your ideas to review by others can spur creativity in unpredictable ways.  Comments can help you flesh out the idea–or spin it in a completely new and fascinating direction.

One thing I like about creating is the lack of predictability. It usually produces meaning and joy in directions you could never have foreseen.

If you don’t have much time, just toss up short items as they strike you. I do that with rough drafts on my Google Notebooks, and sometimes quick posts. (I always want to perfect and flesh them out, though!)

Why blog more often?

Many bloggers do it to reach a wider audience. It’s worth noting that Google ranks blogs higher that have 2-4 new posts/week, as well as those with subheadings, lists and bullets, and links to other websites and blogs. Blogging helps people find your site, using what’s known in marketing as search engine optimization, or SEO.

Google offers a more detailed explanation here.

The short version: Google’s algorithms place high value on the connectivity of the Internet, assuming that the more sites you link to, the better the chance that you’ll be found–and apparently, the more you deserve to be found. Adam Lotz at ROI Media explains the basics well, and notes a few wrinkles and turns that affect the process. The better the site ranking on Google and other measures, the higher your site will rank and more easily be found via Internet searches.

The bottom-line value: your blog or site ranks higher in searches for terms included in the post. And the higher your blog ranks, the easier it is for searchers to find your site, and for you to market your ideas, products or services. So you get more attention, and if you’re doing the right things, more sales.

Blogging also offers health benefits that you may not be aware of. More and more research on creativity and health, including studies at the Harvard Medical School and some published in the New England Journal of Medicine, shows that people who pursue a creative hobby or work live longer and healthier lives than those who don’t. Such hobbies can include writing, knitting, music, playing board games and even sharing stories with friends–just talking about yours and others’ lives!

So if you like blogging, just do it. And appreciate that, unlike most other writing outlets, it’s whatever you want it to be.

#             #             #

h1

Best writing advice: “Keep it short, sharp and punchy”

July 8, 2008

This may be the single best piece of writing advice I have ever heard (and which I cannot find any reference to online).

It came by way of my professor for Persuasive Communication, Dr. Martin (whose first name I can’t recall), at the University of Michigan around 1982.  He said the quote came from Jack Valenti, former speechwriter to President Lyndon B. Johnson:

Keep it short, sharp and punchy.

That says it all for a writer. Do you need anything else?

If you have heard this line, please let me know the source!

               #             #             #

h1

Publication guidelines are better than a style guide

July 8, 2008

A style guide is vital for writers and editors when producing publications and other writing projects. Style guides serve as documentation, created by the editors, that helps guide editors and others who edit, design, write for or otherwise contribute to the publication.

Sometimes, though, a style guide alone can’t do enough.

What is a style guide?

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 an editor must ask herself: Does a style guide do everything you need as you plan, create and manage a publication or online help documentation project?

What are publication guidelines—and how do they differ from a style guide?

The term “publication guidelines” often describes submission guidelines for contributors to a magazine or technical journal.

I use the term in a wider sense: Publication guidelines cover any topic related to the publicationincluding topics that don’t fit in a style guide.

In short, they provide a comprehensive guide, plan and reference source for a publication or set of publications. They work as technical documentation for editors and, to a lesser extent, writers.

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.

What you include in these can vary widely. The publication guidelines published by 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.

Just for fun: 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 astheir 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.

Types of documentation that can benefit from publication guidelines:

  • employee publications like newsletters
  • online product help guides and manuals
  • websites, including intranets
  • marketing publications like emailed postcards
  • brochures
  • any other publications created by an organization

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.

These guidelines can help those not familiar with the project, and who may also be novices with help authoring tools.

The staff that took over this project have varying levels of writing and editing expertise, including some technical writing. But none had expertise with modern help authoring tools. Also 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—called a help authoring tool, used to build the guide.

Click here to compare help authoring tools.

Elements of publication guidelines

What should publication guidelines include?

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 should carry any information that can help writers and editors manage any kind of publication.

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 for 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 and related information
  • 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

How will you know what to include? Simply ask the question: What do I need to know to manage, edit and develop the publication. Then include as much information as you believe any contributor needs to do a good job with their contributions.

Publication guidelines can be streamlined, or as comprehensive as a budget, time, attention and energy allow. It may be best to err on the side of too much information; less is more, for experienced editors and designers.

What you include should depend on a good estimate of the skills and abilities of the team that will take over a project.

How do I start a publication guidelines project?

For a good start on planning and organizing publication guidelines, write a short, clear mission statement and list of specific goals. Put them at the beginning of the guidelines.

Next, develop a tight outline based on those goals. Refine this outline as needed; it will form the skeleton of your publication guidelines. A good outline will guide your project.

Little else is needed except to prioritize and execute each element of the outline.

Click here to see a sample mission statement, goals and outline for publication guidelines.

The bottom line

Writers and editors need guidelines to plan and develop 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.

#                           #                          #

Next:

Follow

Get every new post delivered to your Inbox.