Spring 2003

What’s in this issue?

Contact details...........1

Welcome...................1

Single sourcing............1

Fun stuff....................2

Microsoft Word tips.....3

Understanding project management - part 3...4

Past and future copiesof this newsletter.........4

Monarch Computing ServicesThe Documentation Professionals

Welcome

Welcome to the Spring edition of Monarch News.

In this edition we introduce a concept new to many - single sourcing. Using single sourcing techniques, you can reuse content across several output formats; for example, online help, printed user manuals, intranet, marketing material and training guides.

We include more tips to help you better use Microsoft Word.

The third in our series on understanding project management focuses on the planning and costing aspects of investing in technical writ ing.

Feel free to contact us if you would like more information about particular issues, require help with your documentation projects or have a topic that you would like us to feature.

Single sourcing

What is it?

Single sourcing refers to storing all your content in one place and re-using content selectively in several different types of output. You use a single document source to generate multiple types of output.

What issues can be resolved?

Do you have...

• trouble keeping your documentation up to date?

• difficulty keeping your user manuals, training materials, quick reference guides and online help for your application sychronised?

• different versions of your documentation for users in different countries?

• similar content in more than one manual?

• a printed user manual that you haven't been able to output in other layouts easily?

• links from your application software to context sensitive help that are not working?

The good news is that utilising single sourcing techniques can help with all these common issues.

How can it benefit you?

While it is by no means a 'magic bullet', single sourcing can:

• save a great deal of time and money when designed and implemented correctly

• make your documentation more professional by ensuring that all your documentation is consistent, up to date and easily maintainable

• help you to avoid living with the nightmare of maintaining the same or similar content in different places. For example, your policies and procedures, printed user manuals, online help, training materials, marketing materials and your web site may all have common content. Whenever you make a

Contact detailsMonarch Computing Services

“The Documentation Professionals”

AddressSuite 2, 6 Muster Court

PO Box 6099Vermont South

Vic 3133

Phone and faxPhone: (03) 9884 4343Fax: (03) 9884 5752

Email enquiriesinfo@monarchcomputing.com.au

Web sitewww.monarchcomputing.com.au

See our web site for our statements about your privacy 1

Monarch News

change in one document, you have to remember all the different places where that content has to be updated.

You can use a single document source to

generate multiple types of output.

What are the steps?

Each situation is unique but single sourcing projects typically involve the following steps:

• identify the requirements

• design how best to achieve the desired result, taking into account future opportunities and maintainability

• develop a prototype for a selected number of topics

• review the design and the prototype

• develop draft documentation

• subject matter experts review the draft documentation

• finalise the documentation and deliver across the required layouts

• maintain the documentation to keep it up to date and take advantage of opportunities.

Example of single sourcing

In this example, a fictitious software application is supported in Australia and the USA. The content of the user manual will be very similar but not identical. For example:

• GST in Australia but not in the USA

• different spelling of some words.

Using single sourcing, you only haveone version of all the content. You selectively mark the text or the topic, using one or more of the following tags:

When you generate the output for Australia or USA, you use the tags to determine which content is included or excluded in the deliverable. The first line of the text shown below is tagged for the Australian version and the second line for the USA version.

The following output shown is Microsoft HTML Help, generated for Australian users. This layout is commonly used with online help and context sensitive help.

Note: Context sensitive help is used in software applications. When you are in the application and press F1, the help that is displayed is specific to the window or field you are currently on.

The following Acrobat PDF document was generated within minutes from the same content. This time the output is a printed document for users in the USA.

Want to know more?

We are happy to explain more about how single sourcing techniques could benefit your organisation and demonstrate some examples of what is achievable.

Fun stuff

Aoccdrnig to a rscheearch at an Elingsh uinervtisy, it deosn't mttaerin waht oredr the ltteers in a wrod are, the olny iprmoetnt tihng isthat frist and lsat ltteer is at the rghit pclae. The rset can be atoatl mses and you can sitll raed it wouthit porbelm. Tihs is bcuseae wedo not raed ervey lteter by it slef but the wrod as a wlohe.

2

Microsoft Word Tips

Customising toolbars

When you first install Word, it presents you with certain toolbars that are visible. Did you know that you can:

• select which of Word’s many toolbars you want to have visible

• specify where they are located on the screen

• decide exactly which icons appear on the toolbars

• create your own toolbars with any Word commands on them.

For some people, this will be far too much choice. However, if you are doing the same sorts of things over and over again in your day to day work, it will pay dividends for you to spend time customising Word's toolbars.

Activating toolbars

There are lots of toolbars supplied with Word. To see a list of available toolbars, place your cursor over an existing toolbar and right-click.

The toolbars with the tick mark next to them are currently active. To make an active toolbar inactive, or to make an inactive toolbar active, click on the toolbar name in the list.

Useful toolbars

The Standard and Formatting toolbars are the ones most users are familiar with.

The Drawing toolbar is useful for any graphics activities, such as drawing shapes, WordArt text and adding and manipulating text boxes.

The Reviewing toolbar is very useful if you are editing a document that has Track Changes on. It allows you to add and edit comments in the document and cycle through the changed text without having to keep going back to the menu.

The Tables and Borders toolbar is useful if you are editing tables. It contains a lot of the commands on the Table menu, and useful border and highlighting commands. It also contains commands to change the vertical justification of text in a table cell.

Did you know that you can change the vertical alignment of text in a table using the Tables and Borders toolbar?

The icons shown below let you align the text with the top of the table cell, centre the text in the cell vertically or align the text with the bottom of the cell. Very useful, and these commands don't appear anywhere on the menu!

The Picture toolbar is useful if you have a lot of graphic images to insert into your Word document. Instead of selecting Insert > Picture > From File on the menu, you can just click on the Insert Picture icon on the Picture toolbar.

One click instead of three, which can save quite some time.

Placing toolbars

When you activate a new toolbar, Word places it in a default position. You can move it anywhere you like by clicking and dragging the two grey lines at the left of the toolbar. You can place toolbars by docking them at the top of the document window, at the bottom, to the left or right, or you can have a toolbar that floats over the document window by dropping it anywhere in the window. You move a floating toolbar by dragging the title bar around to the new location.

So, learn a bit more about toolbars and familiarise yourself with the ones that Word provides. If you get enthusiastic, find out how tocustomise toolbars and create newones for your own use. It can saveyou a great deal of time and effortin the long run.

3

Monarch Computing ServicesThe Documentation Professionals

4

Any views or opinions expressed in Monarch News may not represent the views or official policy of Monarch Computing Services.

To the extent permitted by law, Monarch Computing Services and its employees and agents exclude all liability for loss arising from the use of or reliance on the information in Monarch News. ©Monarch Computing Services - 2003. All rights reserved.

Past and future copies of this newsletterThis newsletter will be distributed three times a year. If you do not want to receive future copies, would like to change your details, or would like other people in your organisation to receive the newsletter, please submit your request by email, fax, or phone using the contact details on page one.

If you would like to review past copies of the newsletter, either visit our website to view an Acrobat PDF version or contact us to request printed copies of the newsletter you require.

Understanding project management (Part 3)In this edition, we briefly introduce the process for developing plans and identifying likely costs for technical writing projects. This follows on from the last edition, when we introduced the process for developing business cases and some of the possible benefits.

The fundamental skill needed to d eve l op good p l an s i s 'conceptualisation'. Using past experience and some good thinking, you can conceive the best way forward and the likely outcomes. Mix this in with good feedback from the client on what they need and you have a recipe for success!

The scope of the workThe initial task is to define the scope (or extent) of the work based on the client's requirements. The level of accuracy of the estimate depends on the project. For example:

• You may only need a 'ball park' estimate if the work is of high value or a 'no brainer'.

• The tighter the budget, the more detailed and accurate the estimates will need to be.

For example, one way of accurately defining the scope of a policy and procedures manual is to develop a table of contents based on an existing document and with input from the subject matter experts.

One of our senior writers can estimate the work required in a documentation project based on past experience, theattributes of the deliverables and our historical project records.

Deliverables requiredThe documentation deliverables (output) vary based on the client's needs and opportunities. When planning your documentation project you should consider:

• The form of output. For example, printed user guides, standard operating procedures, online help, user training materials and intranet pages all have different considerations.

• Whether single sourcing is required. See the article on page 1.

• What styles and templates are needed to develop the content efficiently and present the information consistently.

• The target audience. For example, a manual for an engineer proficient in configuring equipment may require less explanation than novice users using an application once a week.

Who will be performing the work?As with all consulting services, experience and talent count. Some writers can take 2-3 times longer to write content and even then the documentation runs the risk of needing rework. Monarch is committed to quality by using experienced, talented and goal-oriented people.

It is often tempting for the subject matter expert to develop the documentation themselves. While the result may be cheaper on the face of it, they may take longer to complete the task than a specialist writer, their other work suffers and the end result may not do justice to their efforts.

Estimating the workOnce you have the information to hand, you can estimate the time required to develop the documentation. This will include:

• Estimates of work for the deliverables through to completion. For example draft 1, version 1 and the final version of a policy and procedures manual.

• Impact on the project timeline of the availability of subject matter experts to review the work.

Developing a realistic budgetThe cost estimate for the project typically depends on the work estimate and the agreed hourly rates for the people performing the work. With a good team effort, costs can be kept to a minimum by:

• Keeping control of the project scope.

• Ensuring the technical writer has the material and tools to get on with the job, including good access to subject matter experts and software applications.

• Constantly trying to improve the efficiency of the process over the life of the documentation. For example, by using single sourcing techniques, templates and style guides to improve efficiency during the development and maintenance phases.

ConclusionMonarch writers are always happy to help with scoping, estimating, developing and maintaining your documentation. In fact, we enjoy it! Give us a call to discuss how we might be able to add value to yourorganisation.