|
Home::Management
Successful Documentation Projects Part 3 of 3 Writing
Author : Glenn Murray
So you understand your user documentation project and youve specced it out. Now youre ready to write. Heres some tips to help you on your way. This article isnt about the actual writing itself; its about the things which go along with the writing. (For information on writing online help, 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 authors 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 dont really facilitate this kind of approach particularly well (e.g., some dont 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 that your user documentation is technically correct and readable, you need to get it reviewed by an intelligent selection of people. For a software project, your review list should include a subject matter expert (generally the programmer), the software architect, perhaps the project manager, and another writer. The review requirements will vary with each draft, so your reviewers and review procedures should be documented 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 isnt very powerful, because theres a tendency for writers to follow instructions as they think theyve written them, not as theyve 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 doesnt often happen, but its 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, its 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 youre 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, youre performing a balancing act. If you send the user documentation to the translators too soon, youll spend a lot of money on changes to the translations. If you send it too late, it wont be ready in time for the release of the product.
Managing change
Its 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
* You can use the same estimating techniques as you used earlier in the project.
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, youll be able to see whether you will meet your milestones and deadlines, and youll 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 youve done over the last month
What you plan to do over the next month
Any issues youve encountered
Manage Production
The meaning of production varies depending on what kind of documentation youre 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 evaluation stage is to consider:
Did the project go according to plan?
Why? / Why not?
How individual team members contributed to the overall project.
How the project manager performed.
Whether the documentation achieved its goals.
Your tracking metrics will come in handy during this stage; if there were any flaws in the project progress, they should go some way towards identifying them. You might also use the sample evaluation report provided by Hackos in Managing Your Documentation Projects by Hackos (1994), pp.514-518.
Is your documentation successful?
Now that youve 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 thats it! Remember, this process is an ideal process. Take the bits that suit you and your project, and leave the bits that dont.
Good luck!
Article Source: http://www.articledashboard.com
* Glenn Murray is a website copywriter, 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 www.DivineWrite.com or www.ArticlePR.com for further details, more FREE articles, or to download his FREE SEO e-book.
Spam emails More free articles Related articles
|
More related feeds |
privat 3 by softwareuser | FreeLance Home Jobs
sLink=/loonkosten/start.asp.The calculation/privat module uses a ACCESS database.In Mambo I wan't to use the "Community Builder" module for the private/calculation part. (Budget: $100-300, Keywords: ASP, PHP, Website Design) ...Say NO to vendor lock-in in education - draft letter to VTU VC
... tools which MS has to offer pales into insignificance compared to the real world engineering (and social) skills a students learns by working side by side with talented developers all over the world on Free Software projects. ... Digital Curation Blog: Edinburgh IT futures workshop
I spent Friday morning at a workshop entitled “Research, wRiting and Reputation” at Edinburgh University. Pleasingly, data form quite a large part of the programme (although I’ll miss the afternoon talks, including Simon Coles from ... (IT) Seeking Solid Stellent Administrator | Hi Wages
... Content - Extensive Experience 3-5 years Systems Administration - Working Experience 0-2 years Technical Documentation - Extensive Experience 0-2 years Stellent 7.5 10g Required Skills: Content Management Web Content Writing Systems ... Telecommute jobs on Craig's list: Part-Time Programming Job for ...
You provide: 1.) well thought out, elegant, readable, well tested code 2.) documentation 3.) custom versions of the code and general support for users. Other projects may be added - A total of 6-12 hours of work will be needed per week. ... Java Universities are Mediocre at Best! « The Minority Blog
Tutorial 2 worked out with lists and stacks which they struggled to understand and the Tutorial 3 had to do with trees and graphs and we were told to be extra benevolent when marking since trees and graphs are too hard for them and the ... Freelance Project | Swf Rotating Images
There are 3 different flash animations created for different web pages. First animation; This website http://tinyurl.com/6qwkvq needs an animated header. This header will show 4-5 products one by one . Main part is, product information ... Cpanel Mysql Create Update | FreeLance Home Jobs
This project consist to create 3 PDF document from data in our mysql database - Invoice - Workin Document - Jobs List Experience in this type of document creation is required Budget is 100.00... (Budget: $30-250, Jobs: Data Processing, ... kitchen table math, the sequel: one child at a time
In June of 2007 I was testing children in the primary grades (reading, spelling and math levels for reporting on a project the school was engaged in). One student, finishing third grade, really concerned me. She had never been flagged ... Voice From Home Video Blog » Blog Archive » The Audacity of Hope ...
The Audacity of Hope Part 1 The Audacity of Hope Part 2 [...] Posted on November 7th, 2008 at 3:42 am. Allen Taylor Said,. Nice writing. You are on my RSS reader now so I can read more from you down the road. Allen Taylor ...
|
|
|
