Want to write an Operations Guide? This tutorial explains how to write your first operations manual. It helps you get started, suggests how to format the document, create the table of contents and what else you need to include in a sample plan.

Operations Guide: Definition

What is an Operations Guide?

Definition: An Operations Guide provides instructions to System Administrators to help them manage updates, maintain computers, and run reports. It also offers troubleshooting information.

Operations Guide: How to Start

The difficulty in writing an Operations Guide, like any technical document, is to know where to start. Here’s a suggested approach:

•  Who – define who will read the Operations Guide, for example, is it developers, testers or users?

• What – identify the most important tasks you need to write to help sys admins. How do you find out? Ask the people who will use it and capture their most urgent needs.
• Where – identify where it will be used. Will it be used online, printed out or read on a mobile device.
• When – is this document used in an emergency? Or is it used in less pressurized settings? How does this affect the content and the way it’s structured? When is it due for completion?
• How – create a list of who will help you write the document, provide answers, review it, and then sign off.
• Others –you’ll also need things like style guides and other supporting documents.

While this may seem a lot, focus on who will use it first and what problems you’re going to solve.

Operations Guide: Define Your Audience

Who’s going to read your Operations Guide? Before you start writing perform audience analysis.

• Identify the main user types (sys admins, testers, developers)
• Pain points
• Urgent needs
• Expectations

This helps structure the content. For example, if you know that developers require in depth information on how to setup a server, then provide very exact step by step instructions.

Operations Guide: Create a Format

If this is your first Operations Guide, use a template to get started.

While the template may not be perfect, it identifies the key sections for the table of contents. Once you have these in place, fill in the gaps and complete the document section by section.

Formatting the document also involves:

• Updating the cover page so it displays the version number, official document title, publication date, and possibly author.
• Updating the header and footers, for example, by including the section or chapter.
• Using a consistent font (or series of fonts) across the document. When you copy and paste from different documents, it’s easy for rogue fonts to enter the document. Use styles to control this.

Operations Guide: Provide an Outline

When the user first opens the document, provide them with an outline of what’s included in the guide. This helps orient the reader so they understand how the operations guide is structured and how information will be presented.

Here’s a sample outline:

Title: IBM WebSphere 9.0 SP3 Operations Guide

Description: This guide describes the major tasks involved in administering and troubleshooting IBM WebSphere 9.0 SP3.

In this guide you will find:

• Administering IBM WebSphere 9.0 SP3
• Troubleshooting IBM WebSphere 9.0 SP3
• Additional Resources for IBM WebSphere 9.0 SP3
• Appendix A: Uninstalling the Database
• Appendix B: Uninstalling SP3
• Appendix C: Settings for Web Services
• Appendix D: Permissions
• Appendix E: Performance
• Appendix F: Database Maintenance
• Appendix J: Setup Codes
• Administering IBM WebSphere 9.0 SP3

This section contains background information and procedures for performing the major tasks involved in administering IBM WebSphere 9.0 SP3.

In this guide:

• Overview of IBM WebSphere 9.0 SP3
• Managing IBM WebSphere 9.0 SP3
• Reports in IBM WebSphere 9.0 SP3
• Securing IBM WebSphere 9.0 SP3

Once you have outlined the high level sections, you can transition into the document, for instance:

“You can use IBM WebSphere 9.0 SP3 to manage downloading database updates from IBM and distributing them to computers in your network.”

Operations Guide: Table of Contents

Now that we have this in place, create the table of contents.

Remember that this will vary depending on your setup but the following sections apply to most Operations Manuals.

Introduction

Introduce the document by describing the target audience and the systems which will be covered by the Operations Guide.

• System overview – explain how the system functions at a high level, for instance, process credit cards, record transactions, or store files.
• Authorized use – identify who is authorised to use the application, for instance developers, testers, and sys admin.
• Points of contact – identify the application owner and how this person can be contacted
• Help desk – provide details of who runs the help desk (technical support) and different levels of support, if applicable.
• Hours of operations – identify when the application is supported, eg 9-5, and when it is scheduled for maintenance, eg every quarter.

System overview

Next, provide a brief description of the operation of the system, including its purpose and uses.

• System operations
• Software inventory
• Software interfaces
• Resource inventory
• Report inventory
• System restrictions
• Hardware

Operations team

Outline the operations team in an org chart. If useful, provide a leadership chart and identify the leadership structure within the team, such as managers, team leaders and domain experts.

It also highlights reporting relationships and reflects the management and leadership structure of the team:

• Organization chart
• Leadership chart
• Key roles & responsibilities
• Anticipated change

Operations schedule

Here we describe how activities are scheduled. Tasks can generally be grouped into daily, weekly and monthly schedules.

Depending on the circumstances, additional administrative tasks may need to be implemented, and some tasks may occur more or less often or not at all.

• Daily tasks
• Weekly tasks
• Monthly tasks
• Backup schedule

System runs

Describe the system runs used by Operations personnel when:

• Scheduling operations
• Assigning equipment
• Managing input and output data, and
• Restart/recovery procedures

Provide detailed information on how to execute the system runs. Provide a run identifier, i.e. a unique number, to reference each run.

System Restores

Finally, describe the steps required to restore operations. Describe:

• Possible failure scenarios and
• Steps to restore operations and data in that scenario

Update Classifications

Another area to consider is update classifications. These represent a specific type of update for different products.

The following table lists samples update classifications.

• Critical updates – Fixes for problems that resolve critical errors.
• Security updates – Fixes that address security issues.
• Definition updates – Updates to definition files.
• Feature packs – New features rolled into products at the next release.
• Service packs – Sets of hotfixes, security updates, updates since product release

Conclusion

In this Operations Plan tutorial we’ve looked at how to identify our readers, how to format the document, and how to create the table of contents. What’s missing is how to write the Operations Plan itself. Next week, we’ll look at this.

Let me know what you think.

What questions do you have about Operations Plan? How can we help you get started?

What is a software documentation plan? This is a project plan for the technical documents you plan to write for the next software release. Like a standard project plan it captures the resources, requirements, costs, and deliverables.

As this is for technical writers, the documentation plan will focus on the content you intent to deliver; it may include the document format, estimated page count, delivery format and other such items.

Software Documentation Plan

In general, your documentation plan (also called Information Development Plan) will include the following sections:

• Introduction
• Data Management
• Guidelines and Requirements
• Schedule and Cost Estimates
• Formatting
• Standards
• Submission Policies

Documentation Plan: Introduction

To start the document plan, outline the purpose, scope and objectives. You must also describe the information to be created (e.g. user guide, online help, and release notes) and how you will store, manage, share and publish the documents.

The other major part of the document focuses on who will help develop the documents (i.e. technical writers, graphic designers, usability experts, testers etc) and also guidelines on the style, format, security and sharing of the files once completed.

Include the following in this chapter:

• Overview
• Purpose
• Scope
• Objectives

Data Management

Next, we look at how the technical documents will be managed across different systems, platforms and sites. In this chapter outline how you will:

• Capture
• Manage
• Distribute and
• Archive project information

To reduce data contamination, set guidelines on how project and product information will be managed effectively.

Project information includes all documentation that supports operations, such as:

• Reviews
• Technical analyses
• Design information
• Technical papers

Include the following in this chapter:

• Requirements for Information Management
• Information Management facilities
• Website
• Intranet
• Technical Library
• Controlled Documentation Lists
• Physical Repository

Documentation Guidelines

Once we have the data management in place, outline the requirements for project documentation and how you plan to prepare and control documents and records.

Include the following in this chapter:

• Preparing Controlled Documents
• Review and Approval
• Public Release of Documents

Time and Production Cost Estimates

This is one of the critical parts of the documentation plan. Your cost projections impacts how you’re funded, issues if you go over schedule, and dependencies on other business units, for example, if they will be charging you for services.

To do this, estimate the amount of time (i.e. total number of hours/days) it will take to complete the documentation task. When estimating the total cost, consider whether the technical documentation exists, requires updating, needs revising or must be developed from scratch.

To do this correctly, make sure you include costs for:

• Interviewing subject matter experts, users, and customers
• Attending and organizing training sessions
• Writing
• Editing
• Production
• Additional software licenses if necessary

Include the following in this chapter:

• Dependencies
• Document Formats
• Final Document(s)
• Printing, Packaging, and Distribution
• Production Estimate
• Production Requirements
• Review Process
• Reviewers
• Schedule
• Time Estimate
• Writing Strategies

Formatting

Most companies use style guides and branding guidelines to control the look and feel of the document. In this chapter, describe the formatting requirements for the technical documentation.

This also reduces any ambiguity or assumptions by the technical writing team on how the documents should be formatted. The information development plan becomes their bible.

Include the following in this chapter:

• Appendix Format
• Bullet Formatting
• Code Formatting
• General Formatting
• Glossary Format
• Graph, Chart, and Screen Capture
• Header/Footer Format
• Heading Formatting
• Table of Contents Format
• Title Page Format

Standards

After you’ve described the formatting guidelines, discuss the writing standards that all technical writers must follow when creating documents.

Highlight that writers must adhere to these standards.

This ensures that the documents are delivered to the correct standard and support the company’s Quality Plan.

Include the following standards in this chapter:

• General Documentation Standards
• Quality Measurements for Deliverables Submitted
• Standards for Software Development
• Standards for Design Team
• Standards for Software Testing Team

Submission Policies

In the final chapter, describe how documents must be submitted for review and approval.

Technical Writers must submit all deliverables according to guidelines in the Quality Assurance Plan.

Include the following in this chapter:

• Review Submission
• Final Submission

Conclusion

These are the main sections required for a software documentation plan. If necessary, you can drill down and add more information for different sections. It really depends on the size of the project and how much documentation is required. Pay special attention to the costs section and give yourself some leeway for scope creep.

Over to you.

What mistakes do Technical Writers make when writing software documentation plans? What’s the most important chapter to get right?

Isn’t the advantage of creating process flowcharts to help the reader see how it works instead of having to read the MS Word document?

But what happens if the process is so complex that the diagram becomes almost unreadable? Instead of helping business analysts understand the process, it adds another layer of complexity. In addition, it makes it almost impossible to discuss the process with your clients. They may even go back to the MS Word documents instead.

Business Process Flowchart – 4 Swim lanes

How do we avoid this?

Understanding Flowcharts

First we need to look at why we create diagrams for business processes. Why not use MS Word documents and discuss how it works that way?

What is a flowchart?

A flowchart is a diagram that illustrates how a process works.

Instead of using words to describe the interactions between people, software, or other ‘actors’ in an activity, the flowchart shows this via shapes, symbols, and directional lines.

This means you can – with a glance at the map – see how the process operates, get instant feedback, and refine the action steps.

You also need supporting text to capture more granular information but the process map gives the high-level snapshot you need.

3 Types of Shapes in Flowcharts

When creating flowcharts, you will use the following shapes to capture most actions:

• Rounded rectangles – show the flow-chart’s start and end points.
• Parallelograms – show inputs or outputs. For instance, an input could be a loan request; the output might be the actual money sent to the customer.
• Rectangles – show the main activities that occur in a flowchart.

How do I show direction in a flowchart?

Use arrow-heads to show the direction of each step in your process. To do this, right-click on a line, select the arrow, and then choose the direction.

If you don’t provide direction, it’s hard for the reader to know where each step goes next…. especially if several lines enter and exit a rectangle.

How to illustrate processes on a flowchart?

In the following tutorials, we’ll look at more complex process mapping but for those who are new to process design, the three types of structures used in flowcharts are as follows:

• Sequences – Show a series of actions, or steps, that are performed in sequence, for instance, the steps required to apply for purchase an airplane ticket online.
• Decisions – Show decision points. The Diamond symbol indicates a Yes/No question. If the answer to the question is Yes, the flow (i.e. direction) goes in one path; if the answer is No, the flow goes in another. This is also called Either/Or.
• Repetitions – Shows parts of an activity that repeats or loops. This is helpful when flowcharting software or business operations.

For instance: the process asks the question “Are your PIN details correct?”

If the answer is No, Process A is performed.

Then the question “Are your PIN details correct?” is repeated.

Process A is repeated as long as the PIN details are invalid.

When the response changes, for example, when the PIN details are valid, the repetition stops.

How to connect large process maps in Visio?

This brings us complex process maps.

You have several choices here:

• Create one master process map with EVERYTHING on it.
• Create one parent diagram and several child diagram (i.e. Visio files).
• Create one parent diagram and use Connectors to link them together.

How do Connectors work?

Instead of linking to other files or creating a suite of files, use Connectors to ‘link’ to other diagrams.
Use Connectors when a flowchart is too detailed to fit onto one page.

Here’s how it works.

1. Identify the sub-processes. Label them.
2. Create a new MS Visio page for each sub-process.
3. Create a master diagram.
4. Illustrate the process at a high level.
5. Use the Connector symbol – small circle with a letter or number inside it – to connect the master process to the sub-process. These are also called off-page connectors.

Tup: One suggestion is to use RED for connectors as they highlight where you go off-page to learn more.

Visio – Process flow diagram

Conclusion

Rather that squeezing the entire flowchart into one page, use connectors to join one page to another page, so that the reader can understand the flow of information more clearly. This makes it easier to edit, review, and update flowcharts.

The skill is using connectors is to distill the process into sub-process first and then use the connectors to link the activities together.

That’s how I do it. How do you concentrate a lot of information into a single process map? I’m on Visio. What tool do you use?

One of the difficulties in writing your first test case is that it’s hard to know where to start. Writing test cases is not that difficult if you understand who you’re writing for and what you’re hoping to achieve.

How to write a test case

What’s the purpose of a test case?

The purpose of a test case is to:

Describe how you plan to verify (i.e. prove) that the software agrees with the specifications.

That’s it.

The next step is to demonstrate that you’ve done this correctly and haven’t modified the findings or changed the result data.

Ideally, when you finish writing the test case, you can give it to someone else, e.g. tester or developer, and they can do the testing with the test case you wrote.

Writing your first test case

Here’s how to keep you test cases practical and effective:

1. Test Case Description – Identify the information necessary to verify the functional requirements.
2. Requirement Traceability – Cross-reference to the number in the specification (SRS) document.
3. Purpose – Describe the software features that will be tested; the behavior being verified, for instance, when you click A, B occurs.
4. Procedure – Describe how to perform the test. Keep the text simple and make sure the reader doesn’t ‘interpret’ what you’ve written. For example, “Click the Save button on the menu to save the document.”).
5. Test Data – Include the exact input data that will be provided and the output for each case. Include any manual calculations necessary to determine the outputs.

Formatting your test case

You can use either Microsoft Word or Excel. I suggest that you use tables to structure the data and make it easier to read.

• Represent test data in tabular form
• Create one column for input items and
• Create one column for expected outputs

If the input data is held in an external file, identify the file name and its location.

What else would you add?

What’s the best way to write a Software Maintenance plan? Software Maintenance Plans are different than other technical documents in that the focus is on how to modify software AFTER it has been released and is now in operations. Most other documents focus on planning, development or testing.

Download Now

How to Write Software Maintenance Plans

So, what do you need to include in your Software Maintenance Plan?

Software Maintenance planing includes ten activities:

1. Preparation – Describe software preparation and transition activities including the conception and creation of the maintenance plan; describe how to handle problems identified during development and configuration management.
2. Modification – After the application has become the responsibility of the maintenance team, explain how to analyze each request; confirm and check validity; investigate and propose solutions; document the proposal and get the required authorizations to apply the modifications.
3. Implementation – Describe the process for considering the implementation of the modification itself.
4. Acceptance – Describe how the modification is accepted by the maintenance team.
5. Migration – Describe any migration tasks that need to be executed. If the software needs to be moved to another system, outline the steps to do so without impacting its functionality.
6. Transition – Document the sequence of activities to transition the system from Development to Maintenance.
7. Service Level Agreements – Document SLAs and maintenance contracts negotiated by Maintenance.
8. Change Request – Outline the problem-handling process to prioritize, documents and route change and maintenance requests.
9. Modification Request acceptance/rejection – Describe the request including details of the size/effort/complexity. If this is too complex to resolve, outline the steps to route the issue back to the software team.
10. Retirement – This is the final stage in the lifecycle. Describe how to retire the software and the steps to archive any data that may be a by-product of the system.

Takeaway

There are two sides to Software Maintenance Plans – management and technical.

• Management issues include aligning with customer priorities, resources, setting up maintenance teams, and costs.
• Technical issues include impact analysis, testing, maintainability measurement.

Next week, we’ll look at how to write your Maintenance Plan and what areas you need to document.

How do you know whether you are writing well?

There’s only one test that really matters: when your audience understands your information and is moved to act in accordance with your goals.

But how will you know when this happens?

The odds are pretty good that, early in your career anyway, you won’t have any automatic indicators. Sometimes you will be writing a decision paper, and your decision will be adopted as the company line, and this is a good self-test.

But this won’t happen often; more often than not early in your career your writing will not be directly acted upon.

Usually you’re going to have to solicit feedback.

What else would you add?

What’s the difference between an Operations Manual and a Procedures Guide? At first glance, it’s easy to see the confusion as both contain procedures that need to be followed. However, if we look at them a little more closely, we can where and how they differ.

Operations Manuals v Procedures Guides

Samantha emailed me to ask about preparing ‘an operations manual for my employer.’

There were two main criteria:

‘The main task is teaching examination skills to health professions, such as doctors and nurses.

My boss wants a manual that will enable anyone to show how things work and to cover any gaps in knowledge when key personnel are no longer available.

The document should detail the what, why, who, when, and how.

Which one of your templates will enable me to best build such a document?’

Here was my response:

Re: My boss wants a manual that will enable almost anyone to keep the show going in the event that any of the key personnel are no longer available.

Use the procedure templates for this type of activity rather than our Operations Manual template.

The reason I say this is that other companies have used this template to capture how different tasks are achieved and maintain them going forward.

The approach I’d take is to:

• Define all the tasks you want to capture
• Create a Table of Contents
• Write a procedure for each task

The difference between the two type of documents is that the Operations Manual is usually focussed on the operations of an IT system.

For example, what tasks do you need to perform to operate the system on a daily basis? The focus is technical and specific to software (or an application, network, or hardware.)

Whereas… procedures show someone the steps to follow to perform a task, which may not be technical.

For example:

• How to check a customer’s credit card statement.
• How to apply a discount to a customer’s account.
• How to update the HR database every quarter.

And so on.

PS – If you’re new to Technical Writing, or have been asked to write technical documents, and don’t know where to ask, send me an email and I’ll show you the best way to get your documents under control.

Here are three ways to use AutoCorrect to fix errors in your technical documents:

• Capitalization options – AutoCorrect can capitalize the first word in a sentence, the names of days of the week, the first letter of text in a table cell, and so on.
• AutoCorrect entries – AutoCorrect can use a list of built-in corrections, called AutoCorrect entries, to detect and correct typos, misspelled words, and common symbols. You can easily remove unwanted entries or add your own entries.
• Spelling checker corrections – AutoCorrect can use corrections that are generated by the spelling checker’s main dictionary.

Using AutoCorrect To Fix Mistakes In Your Technical Documents

To add an autocorrect entry, follow these steps:

1. On the Tools menu, click AutoCorrect Options.
2. In the Replace box, type a word or phrase that you often mistype or misspell – for example, type Oralce.
3. In the With box, type the correct spelling of the word – for example, type Oracle.
4. Click Add.

Using AutoCorrect To Fix capitalization and spelling errors

To prevent specific capitalization and spelling corrections:

• On the Tools menu, click AutoCorrect Options.
• Click Exceptions. Do one or more of the following to prevent AutoCorrect from:

To capitalize a word you type after a specific abbreviation:

• Click the First Letter tab, and then type the abbreviation (including the period) in the
• Don’t capitalize after box.

To correct a word that contains mixed uppercase and lowercase letters:

• Click the INitial CAps tab, and then type the word in the Don’t correct box.

To correct a spelling error:

• Click the Other Corrections tab, and then type the misspelled word in the Don’t correct box.
• Click Add, and then click Close.

Which is better for writing long technical documents? Adobe FrameMaker or MS Word? I’ve prepared a list of the strengths and weaknesses of each tool. Take a look and tell me what you think. And which is the best value for money?

Adobe FrameMaker or MS Word?

This article compares Microsoft Word and Adobe FrameMaker by examining the following key areas:

• Ability to create Long Documents
• Short Documents
• Using Microsoft Word as a DTP Tool
• Printing and Type
• Cross-platform capabilities
• Word’s Nice and Not So Nice Features
• Importing Graphics
• Indexing

Over the past decade, Adobe has created a suite of publications software, with FrameMaker fulfilling the role for documentation generation. Adobe said that development plans for the immediate future include enhancing the import and export of files from one format to another.

Companies that choose FrameMaker are safe-guarded regardless of future documentation standards, i.e. XML, SGML, Acrobat, or HTML.

MS Word’s Weaknesses

• Word doesn’t handle large documents well and begins to have difficulties when it goes over 100 pages of standard text, i.e. combination of graphic and text formatting.
• Compiling the TOC and indexes for multiple files takes much longer in Word than FrameMaker.
• Microsoft Word is not a desktop publishing program — It’s a word processor.

FrameMaker Strengths

• Ideal for large books i.e. 200 pages +.
• Before you start, define your template. Using templates in Word is far from ideal as they tend to corrupt when under stress, i.e. if you have too many bullet list and graphic import, it will start to generate error, such as inserting paragraph marks in the header and footers.

FrameMaker Weaknesses

• Expensive
• Steep learning curve
• Possible being phased out by Adobe. Replaced by InDesign?

The real advantage to FrameMaker is the ease at which documentation, indices, and cross-references is easily updated. Page, section, figure, table, and even equation numbering can follow any scheme you can think up. FrameMaker is best on 1280 x 1024 monitors, and can be difficult to use on small screens.

FrameMaker is designed specifically for long complex documents, which can be edited, updated and changed, including the TOC and indexes very easily.

 Short Documents

If your documents are under 100 pages on average, FrameMaker is probably not required. Also, the word processing functions in FrameMaker i.e. spellcheck, redo, undo, sort, are not up to Word’s

MS Word as a DTP Tool

Word was not designed as a DTP program — it’s a word processing program that has added features over releases, so that if can be used for less intensive publishing requirements. To be more specific:

• It does not handle any color separations
• Poor support for page layout and/or graphic placement i.e. you cant rotate graphics.
• Not designed as a structured document tool, i.e. cross-referencing other books. Master Document feature is meant to address this, but is notorious for collapsing.

Printing

• FrameMaker is excellent for producing printed manuals. Very little deterioration occurs when printing complex documents across a range of printers and operating systems.
• FrameMaker is more connected to the publishing world, and has very close ties to Adobe’s other technologies, such as the Adobe Type Manager, Postscript and Acrobat PDF.
• If you have to print large documents in Word, you’ll most likely end up having to split the document into smaller files, changing the header and footers accordingly, hard-code the TOC’s and having nightmares with any cross-references. Avoid at all costs!

Type

FrameMaker’s quality of typography is better than most DTP packages, and significantly superior to Word. FrameMaker is very useful for intensive printing jobs where, for example, you can utilize Postscript.

Cross-platform

• Frame’s cross-platform capabilities are very impressive. No other commercial DTP package runs across so many platforms.
• FrameMaker prints identically on Unix/Mac/Windows — but you need to be using the same FrameMaker release.

Word’s Nice Features

• When you highlight a word, Word highlights the next space, which improves cut & paste.
• The Insert Symbols dialog box is faster and more intuitive than FrameMaker’s Help Keyboard Maps mechanism.
• Word offers several views of a document, including a non-WYSIWYG view that works well on typical landscape monitors.
• Autotext, Autocorrect and the Macro Recorder are very helpful.

Word’s Not so Nice Features

• Formatting diagrams and images is awkward and prone to crashing the system.
• Temporary Word files will eat up your disk space, and sometimes don’t get deleted from the cache.
• You can’t have text on one page with different directions, headers and footers horizontal and, for example, a vertical pictures description.

Importing Graphics

There is a distinct difference between they both handle graphics:

• FrameMaker imports graphics, which have been either copied directly into the FrameMaker file, or referenced from another location. This method is recommended as the files size doesn’t bloat and when you update a graphic, it is automatically updated in the document.

Word copies the file directly into the document.

Therefore, when you change or update the source graphic, you need to import it back in again, re-size and layout it etc. Importing files into Word tends to increase the file size rather dramatically.

We’ve seen files double from 2MB to 4MB and continue to double until they reached 64MB – with no additional graphics been added. When Word has difficulties, it tends to expand in size. This can result in been locked out of your document, as your PC will run out of memory.

Also remember that because Word copies the files in, rather than import them, when you make updates to your application, and screenshots needs to be updated, you have to go through all the Word documents again. This is very expensive and alone can justify the value of purchasing the FrameMaker product.

With graphic heavy files, Word will grind to a standstill and not display any graphics towards the final pages, if you get that far. It consumes all memory available and then some more.

Indexing

FrameMaker has very advanced indexing capabilities:

• You can index to several levels
• You can provide different types of indexes and lists, e.g. have an index of multiple chapters (each chapter being a separate file)
• You can have lists of the tables and figures, which are compiled automatically. These are automatically brought in by referencing the file, and are automatically formatted
• You can track the imported graphics on a list, and have the number of pages in each chapter, TOC, index, glossary created automatically in another compiled index
• Microsoft has rudimentary indexing, but nothing near the capability of multiple indexing that FrameMaker has.

Cross-references

FrameMaker automatically cross-references document paragraphs, including those in multiple files. Cross-references include:

• Text
• Paragraph numbering
• Figure titles
• Table titles
• Numbers
• Microsoft Word does have these advanced features.

Formatting

FrameMaker again has very powerful features, such as:

• Formatting multiple paragraph number schemes within a document.
• Creating bullets with any character type.
• Running headers and footers using referenced paragraphs, i.e.,
• Paragraph heads.
• Formatting tables using table templates, ensuring that you use a consistent format for each type of table.

Word has a limited and mutually exclusive form of paragraph number schemes. The formatting is tied to the rest of the paragraphs, making it extremely difficult to format different fonts, styles, sizes, etc. within the same numbering stream, or to have multiple numbering streams. Word does not number your tables or your figures.

Printing

Word changes fonts and pagination unpredictably when you change printer drivers. That means you can’t proof on laser prints, unless your laser writer drivers give you reliable PostScript output on the page size (plus crop marks) that you’ll need for final output.

Generating TOC

• FrameMaker creates TOCs and indexes across the whole book.
• In Word, you can make indexes and TOCs using the Reference Document program.

User Groups

Word User Groups tend to be more active than those for FrameMaker, partially because of Microsoft’s support.

Converting from Word to FrameMaker

The overall conversion process is time-consuming, with an initial expensive outlay, and may involve template design and other production factors. Before making the plunge, you might want to get a demo, produce some documents and seeing how you like it.

Online Help

If you are planning on providing on-line help for a Windows-based software product, Word’s conversion to on-line help is a lot easier than Frame’s.

Reference Documents

• In Word, if you create large documents, when you come to printing all sections and creating TOC’s, difficulties usually arise. Word is not designed for this, and what you are asking it to do it beyond its scope.
• Once Word begins to degrade, everything will go awry and you’ll get mis-numbered pages, TOC entries with unresolved pages, mangled headers and footer, and other idiosyncrasies.

Graphics

• FrameMaker is best for document creation that includes large amounts of graphics, and graphic layout re-formatting i.e. rotation.
• Word’s performance degrades with imported graphic files —you’ll soon hear your PC desperately grinding in the background trying to swap memory—and the file sizes in Word increase to enormous proportions during graphic imports, beyond all reasonable logic.
• Remember, when you import a low-res file format, e.g. GIF/JPG, into Word, it is converted into BMP, which partly explains the sudden increase.

Templates

Creating templates in Word is fairly limited, as its essentially designed for writing letters. Also, you can’t open a Word template while other users are using a document based on this template.

Pagination

Word tends to change pagination when you change printer driver, even if the fonts have not changed, ruining indexes and tables of contents.

OLE Support

FrameMaker doesn’t support OLE.

Bookmaking

FrameMaker is fast and intuitive.

Endnotes

• Word supports true endnotes.
• FrameMaker does not. FrameMaker has a workaround using cross-references, but this is cumbersome when working with a book with many component documents.

Long footnotes

• Word supports long footnotes, i.e. notes that must be split across successive pages.
• FrameMaker does not support long footnotes. If a footnote is too long to fit on the page on which its marker appears, the entire footnote text is moved to the next available page.

SGML

With FrameMaker+SGML, you have the combination of FrameMaker’s features, and create an SGML document that can be used with a database search engine.

Adobe and FrameMaker future plans

Adobe has assembled a collection of documentation software, with FrameMaker central to that strategy. Adobe said that development plans for the immediate future include enhancing the import and export of files from one format to another.

Companies that choose FrameMaker are safe-guarded regardless of future documentation standards, i.e. XML, SGML, Acrobat, or HTML.

Those are some of my thoughts.

What do you think?FrameMakerFrameMaker

You can setup MS Word so that it automatically fixes mistakes you make in your documents.

To automatically detect and correct typos, misspelled words, and incorrect capitalization, use the AutoCorrect feature in Word.

How to Fix Errors in Technical Documents Automatically

For example, if you type erport plus a space, then AutoCorrect replaces what you have typed with “report.”

Or if you type ‘Teh Executrie summary states‘ with a space, AutoCorrect replaces what you have typed with “The Executive Summary states.”

You can also use AutoCorrect to quickly insert symbols that are included in the built-in list of AutoCorrect entries. For example, type (c) to insert (c).

Note: Text included in hyperlinks is not automatically corrected.

To autocorrect your Word Documents, follow these steps:

1. On the Tools menu, click AutoCorrect Options.
2. In the Replace box, type a word or phrase that you often mistype or misspell – for example, type Micorsoft.
3.  In the With box, type the correct spelling of the word – for example, type Microsoft.
4. Click Add.