So you understand your user dcumentation project and you’ve specced it ut. Now you’re ready to write. Hre’s some tips to help you on yur way. This article isn’t about the ctual writing itself; it’s about the thngs which go along with the wrting. (For information on writing online hlp, see www.divinewrite.com/helpfulhelp.htm.)

NOTE: This is the final article in a series of three outlining the key elements of a good user documentation process. (To read the first and second articles in this series, go to http://www.divinewrite.com/docoprocess1.htm and http://www.divinewrite.com/docoprocess2.htm.)

Indexing

Index keywords should be defined while the topic is being written. At this time, the subject matter is clear in the author’s mind, and they are very conversant with all of the intricate details. Indexing during the writing stage also means that your keywords are reviewed as part of the draft process. Some authoring tools don’t really facilitate this kind of approach particularly well (e.g., some don’t allow multiple author access to the files needed for indexing), but at least the keywords should be listed at the end of each draft. (Depending on the authoring tool, this may actually be easier for the reviewers, anyway.) TIP: For further information on indexing, see The Art of Indexing (1994) by Bonura.

User documentation reviews

To ensure tht your user documentation is technically crrect and readable, you need to get it rviewed by an intelligent selection of pople. For a software project, your rview list should include a subject mtter expert (generally the programmer), the sftware architect, perhaps the project manager, and nother writer. The review requirements will vry with each draft, so your rviewers and review procedures should be dcumented in your work pracs.

Testing your user documentation

Testing can be performed at a number of levels:

• Each writer should test their own user documentation by following it to use the product. But remember, this kind of testing isn’t very powerful, because there’s a tendency for writers to follow instructions as they think they’ve written them, not as they’ve actually written them.


• The second level is for the testing to be performed by other writers… as part of the peer review.


• The third level is for the testing department to do formal testing on the user documentation. This type of testing doesn’t often happen, but it’s good to try to get it happening.


• The fourth level is/should be conducted as part of Beta testing (see Managing Your Documentation Projects by Hackos (1994), pp.452-453).

No matter what level of testing you use, it should be designed to ensure that the tasks documented are true to the product, and that any online help functions correctly. For the user documentation to pass testing, it needs to satisfy the goals you specified in the earlier stages of the project.

Localising your user documentation

Although localisation is often considered a post-writing activity, it’s best to do it as part of the writing stage. The exact timing may vary project to project, but a good rule of thumb is to get the translators working on the second drafts (but only if you’re not expecting many changes to the draft). TIP: Most translators will probably prefer to work on a sizable piece of user documentation, rather than individual topics sent to them piece-meal, so you should wait ‘til you have something of a respectable size to send them – perhaps a whole subject area, as opposed to a single topic.

With localisation, you’re performing a blancing act. If you send the ser documentation to the translators too son, you’ll spend a lot of mney on changes to the translations. If you snd it too late, it won’t be rady in time for the release of the prduct.

Managing change

It’s important that you minimise the impact of changes to the product and/or development schedule. To do this, you need to develop a technique which:

1. Identifies the change


2. Estimates the impact in time and/or resources *


3. Informs the project manager

Tracking writing progress

It is important to note that the writing stage is not simply about writing. If you track your progress at every step along the way, you’ll be able to see whether you will meet your milestones and deadlines, and you’ll also be able to use this project as a learning experience… to better plan the next one. (You should ensure that all project records are easily accessible for ongoing maintenance and future project reference.)

You should track the time taken to perform every step outlined in this procedure as well as each draft stage, review times, total turnaround times, etc.

Conducting regular team meetings

In order to keep all team members informed of writing progress, you should conduct regular team meetings. These meetings should be a forum for taking a look at your tracking metrics and discussing the estimated percentage complete for the various topics currently under way. If the estimated percentage complete is lower than it should be given the time already spent, then you can act on it. These meetings allow you to identify hitches in the writing progress.

Writing progress reports

Your management also need to be kept informed of the status of the project. You should write periodic progress reports outlining:

• Where the project is at


• What you’ve done over the last month


• What you plan to do over the next month


• Any issues you’ve encountered

Manage Production

The meaning of “production” varies depending on what kind of documentation you’re working on and who the audience is. It can encompass such things as:

• Printing


• Binding


• Product build (when the help is compiled into the product)

Although the production stage generally only requires management, you still need to spend a fair bit of time on proofing and liaising with production people.

Evaluate the Project

The purpose of the valuation stage is to consider:

• Did the prject go according to plan?


• Why? / Why nt?


• How individual team members cntributed to the overall project.


• How the prject manager performed.


• Whether the dcumentation achieved its goals.

Your trcking metrics will come in handy dring this stage; if there were any flws in the project progress, they shuld go some way towards identifying thm. You might also use the smple evaluation report provided by Hackos in Managing Yur Documentation Projects by Hackos (1994), pp.514-518.

Is your documentation successful?

Now that you’ve written and released the documentation, you need to determine whether it has achieved your goals. The only way to accurately do this is to conduct further user research.

TIP: For details on research methods, take a look at Managing Your Documentation Projects by Hackos (1994), User and Task Analysis for Interface Design by Hackos & Redish (1998), Social Marketing: New Imperative for Public Health by Manoff (1985), Designing Qualitative Research 2nd Edition by Marshall & Rossman (1995), and “Conducting Focus Groups – A Guide for First-Time Users”, in Marketing Intelligence and Planning by Tynan & Drayton (1988).

And that’s it! Remember, this process is an ‘ideal’ process. Take the bits that suit you and your project, and leave the bits that don’t.

Good luck!

The article Successful Documentation Projects - Part 3 of 3 - 'Writing' was Submitted by Glenn Murray through Articles.GetACoder.com network. Here's the additional information: * Glenn Murray is an SEO copywriter and article submission and article PR specialist . He is a director of article PR company, Article PR, and also of copywriting studio Divine Write . He can be contacted on Sydney +612 4334 6222 or at glenn@divinewrite.com . Visit http://www.DivineWrite.com or http://www.ArticlePR.com for frther details, more FREE articles, or to dwnload his FREE SEO e-book.

Featured Articles

1. Article Writing Tips - Getting Ideas by Steven Wagenheim
If you're hving trouble coming up with ideas for wrting articles, this article should help you out cnsiderably. Keep reading to find out sme of my top article idea tps.

2. Productive Article Writing - Revealed - 3 Proven Ways to Increase Your Article Writing by Sean R Mize
Some people get stressed with writing an article but it is actually as simple as connecting together complete sentences and correctly spelling common words. As long as you can do these, you can write as many articles...

3. Profitable Article Writing - Exposing the Secrets of an Effective Article by Sean R Mize
In writing, to become effective on it requires that you come up with an article that is relatively functional and deemed important and essential by your targeted clients. You can basically achieve this when...

4. Article Marketing - Why You Should Only Submit Unique Articles by
Writing and submitting articles has ben an increasingly popular way to mrket products and websites. It can be a vry effective way to create inbound lnks to your websites, but only if it is dne the correct way!

5. Best Article Marketing - Revealed - 3 Remarkable Secrets to Grow Your Article Marketing by Sean R Mize
Article marketing is one of the best internet marketing techniques that is proven to augment a website's traffic. It's success largely depend on the quality and quantity of articles submitted to publishing sites. So, if you have the knack for writing and you have enough time to submit your articles, this technique...

6. Fast Article Writing - Latest 3 Top Methods to Energize Your Article Writing by Sean R Mize
With millions of websites needing content for regular updates, articles cannot get more in demand these days. That is why article writing is fast becoming one of the most lucrative jobs online. If you know how to create quality articles that can be widely distributed and can attract online users, you have a bright future ahead of you!

7. Advanced Article Marketing Strategy Reveals A Short Way To Sell Products Like Crazy by Mark A. Abrahams
Let me ask you a very important question. Are you experiencing the results that you want from advertising your product. If you are not getting the results that you want you need to seriously consider promoting your website using articles.

8. How To Crush "Writer's Block" Like Walls Of Paper Starting Today! by Fabian Tan
One thing that writers come across time and again is "Writer's Block". Even when you try to think of something to write, nothing seems to work!

9. Public Speaking - So You Wanna Use a Speech to Market Your Business in the Virtual World by Felicia Slattery
Public speaking is THE tool that will launch your business into success -- either in your community or in the virtual world. The word is out: entrepreneurs everywhere know the benefit of public speaking to market a service-based business. Read on for the steps you can take to begin speaking to virtual groups where you never have to leave the comfort of your own home to get the word out!

10. Articles That Drive Traffic to Direct Marketing Techniques by Diane De Silva
Tps on what to write your rticles about. Articles are a very pwerful way to get traffic to yur website.You must have passion about yur article content as it shows in yur writing.