Successful Documentation Projects Part 3 Of 3 Writing

Successful Documentation Projects Part 3 Of 3 Writing

Successful Documentation Projects Part 3 of​ 3 ‘Writing’
So you understand your user documentation project and​ you’ve specced it​ out. ​
Now you’re ready to​ write. ​
Here’s some tips to​ help you on​ your way. ​
This article isn’t about the​ actual writing itself; it’s about the​ things which go along with the​ writing. ​
For information on​ writing online help,​ see ​

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// and​ http//
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 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 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.452453.
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​ postwriting 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 piecemeal,​ 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​ balancing act. ​
if ​ you send the​ user documentation to​ the​ translators too soon,​ you’ll spend a​ lot of​ money on​ changes to​ the​ translations. ​
if ​ you send it​ too late,​ it​ won’t be ready in​ time for the​ release of​ the​ product.
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
* 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,​ 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​ 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.514518.
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 FirstTime 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!

Successful Documentation Projects Part 3 Of 3 Writing

Related Posts:

Powered by Blogger.