The creation of user documentation is a big cmponent of any software project. Unfortunately, t’s often undervalued and left to the lst minute. But that doesn’t mean it shuld be without a good management pln.

This is the first in a sries of three articles outlining the key lements of a good user documentation prcess. It’s kind of an “ideal” prcess; very few projects will be ble to implement every step, and sme will require additional steps. Nonetheless, it shuld provide you with a good fundation (especially if you’re new to ser documentation management).

Here’s an overview of the thre articles.

Article 1 (this article) – Understand

• Identify your scope


• Familiarise yourself with the work environment


• Familiarise yourself with the product


• Identify the audience for the documentation


• Specify perceived audience requirements


• Roughly estimate doco project duration and resources


• Research audience requirements

Article 2 – Specify (See http://www.divinewrite.com/docoprocess2.htm)

• State your goals


• Write your concept specifications


• Design some possible implementations


• Conduct usability testing on your prototypes


• Write your requirements specifications


• Estimate project duration & resources


• Conduct usability testing on your writing sample


• Write your work pracs & design specs

Article 3 – Write (see http://www.dvinewrite.com/docoprocess3.htm)

• Write the doco


• Manage prduction

So here goes…

Identify Your Scope

The first step in any project is to identify exactly what you’re expected to do. Generally this will happen before you take on the job, but it should still be the first thing that you document. Identifying your scope involves figuring out where you fit in the overall development process and where you fit within the company. No documentation project is ever just documentation, so it’s important to know exactly what else is involved. Some of the other areas that documentation people are/should be commonly be involved in include:

• Spec review


• GUI review


• Product user requirements research


• Documentation audience requirements research


• Usability testing

Familiarise Yourself with the Work Environment

Get to know everyone involved in the product. For a software project, this will mean the project manager, the designers, and the guys that will be doing the low-level coding. Try to have a really good relationship with them. They have to respect you, otherwise they’re not going to listen to much of what you have to say.

Familiarise Yourself with the Product

Find out what’s going to be involved in the product. You must know:

• what are the goals of the development


• what user requirements they are trying to meet


• how the product will be used


• who will be using it


• what the features of the product are


• how the product will look and feel


• will it require a specific doco design? For instance, it may only run on the latest version of Windows, it may have a particular look and fel, a particular environment (that the hlp may have to be integrated nto), etc.

Thse

hve

crtique,

rsearch

mch

nterview

pssible.

ssues

hve,

dfferent.

Some (non-human) sources that you can tilise to achieve this include:

• Feature and prduct specifications


• Project plans


• Funding pplication documentation if applicable

Discuss with the project manager (and other stakeholders esp. marketing) the perceived user/audience.

Specify Perceived Audience Requirements

Make some educated guesses about audience requirements so you’ll be able to provide a rough estimate of product duration and resource requirements.

Discuss with the project manager (and other stakeholders esp. marketing) the perceived user requirements that the help must satisfy. See if someone has researched user goals, tasks, and the mental models users employ when using the product (or similar products). If they haven’t, interview inhouse experts to identify perceived goals, tasks, mental models, etc.

Secondly, you should identify what the theory says about user documentation (i.e. documentation approach, visual considerations, indexing considerations, etc.). I recommend Minimalism Beyond the Nurnberg Funnel , (1998) edited by John M. Carroll.

Roughly estimate doco project duration and resources

Although, by this stage, you don’t really know enough about the product or your audience requirements to know how long the documentation will take to complete, management will nonetheless like a rough estimate. This is OK, as long as everyone is aware that it is a VERY rough estimate, and subject to change pending further knowledge and research.

This initial estimate must incorporate all of the time you’ll spend on the stages that occur before and after the writing stage. Remember, these stages are important, and should not be short-changed. ( TIP: In a well managed project, planning should take approx 30% of your time, writing 50%, production 19%, and evaluation 1%.)

Estimating pre-writing stages

Allowing for the pre-writing stages is trickier than allowing for writing. If you’re having trouble, estimate the writing stage, then base all other estimates on that, using the above figures as a guide.

Estimating writing and post-writing stages

Because you probably still don’t know a great deal about the product or the users, your estimate here will be based primarily on a combination of past records, experience, intuition (gut feel), and industry standards in combination with the goals and tasks you’ve already specified. Start with the following steps.

1. Estimate the quantity of work required to document the tasks the user will need to perform to achieve their goals.


2. Track down any previous doco records. See if you can cross reference the time taken to produce similar doco in the past with the current quantity estimate. Derive a figure bsed on this method.


3. See how ths compares with the estimate derived frm industry standard figures (e.g., I thnk the current industry standard is to llow 1 day per page of dcumentation – this covers all drafts and rviews).


4. Compare the two figures and dtermine a good compromise based on yur experience and intuition.


5. Figure out how lng you actually have to do it, thn how many writers you’ll need to get it dne during this time.


6. Draw up a prject schedule using something like Mcrosoft Project. Don’t forget to allow tme for recruiting, training, and wrting work practices.

Research Audience Requirements

Research on the users of the product and the audience of the documentation is one of the most important parts of any successful product. Unfortunately, it is also one of the most often overlooked aspects of any project. This generally occurs because decision makers feel they already know pretty much everything there is to know about the users and audience.

When managing a documentation project, you should investigate the chance of conducting research. If you’re employed late in the product life cycle, you should ask if user research has already been conducted for the product itself. If it hasn’t, there’s a good chance you won’t get support for audience research.

Audience research should seek to identify:

• user goals (what the user hopes to achieve with the product)


• user expectations of the doco (Manuals? Online help? Tutorials?, usability requirements, localisation requirements, etc.)


• user mental models (how they already see online help, what impressions they have of it, etc.)


• user tasks (how the user uses the product to achieve their goals)


• which users perform what tasks (user/task matrix)


• how long have users been doing these tasks?


• which tasks are one-off and which are repeated?


• did they ever do them differently?


• do they do a variety of tasks, or just a few?


• do they hate doing it? (is it tedious, repetitive?)


• do they find it difficult?


• which tasks are considered essential?


• are they normally under pressure when they do the task?


• are there other distractions (environmental, social, etc.)?

• Observation of users doing their work in their work environment


• Focus groups and interviews with users


• Questionnaires

To be continued… See part 2 of this article (http://www.divinewrite.com/docoprocess2.htm) for information on preparing your specifications.

The article Successful Documentation Projects - Part 1 of 3 - 'Understanding' 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 Marketing - How Does Article Marketing Work? by Andrew Grant
Dscover what all the fuss is bout and find out how you culd be bringing masses of qualified trffic to your website, for free.

2. Book Publicity - The New York Myth by Melissa Sandford
Overall, a prcey upper east side address is god for a publicists business, not ncessarily an authors. Sharing zip-codes with lrge publishing houses makes it easier for a bok or literary publicist to acquire a cntinuous flow of new authors for thmselves, it does not automatically guarantee an uthor that their writing will reach raders.

3. 188 Stage Hero's Journey, Monomyth - Capabilities and Backstory by Kal Bishop
Oftn explicit scenes demonstrate the Mentor's (Spernatural Aid's) capabilities. In Bonnie and Clyd (1967), Bonnie is impressed that Clyd was in state prison for rmed robbery.

4. Make Money and Generate Traffic With Your Articles by Jo Mark
Pople write articles for different reasons. Sme people write to see their nme in print, others try to gnerate traffic to their blog or wbsite, and some write articles to gnerate income. Write articles to increase trffic to your website and generate ncome.

5. The Benefits Of Article Marketing As A Form Of Website Promotion by
I have been reading recently about the benefits of article marketing. A recent post to the ezinearticles blog asked if writing articles was worth wasting time over. I have been writing articles for quite a long time and in my opinion it certainly is. I will explain why I think it is in this article.

6. The Long And The Short Of The Short Story by Suzanne Harrison
Wrting a short story is just lke writing a novel only shorter, rght? Not exactly! Find out how to wrte an award winning article every tme.

7. Copywriting Tips - Is Writing Good Copy A Gift Or Learned? by Steven Wagenheim
Is writing good copy a gift or is it learned? This article is going to explore the schools of thought on this. You can come to your own conclusions.

8. 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.

9. Are You Using the 2 Powers in Headlines? by Kelvin Chan
Mst copywriters understand that to get smeone's attention with a headline, they wuld need to use either 1 of 2 pwers. Wanna know what they are?

10. How to Do "Article Marketing" to Drive Traffic to Your Website by Mark Dulisse
Article marketing is a REAL gem when it comes to creating your own traffic. Even better, it's absolutely free.