Forum Moderators: phranque

Message Too Old, No Replies

Writng a web owner manual

How to organize it?

         

henry0

9:40 pm on Nov 1, 2007 (gmt 0)

WebmasterWorld Senior Member 10+ Year Member



I need to deliver a web owner manual for a large site we just delivered (including custom-made CMS, multiple image/gallery loaders, HTML and .txt email constructor and sender etc..)
That thing will have probably about 30 pages
But I have never written a manual before, my concern is that from our stand point of view (because we built it) it will make sense but the reader might have a different opinion on the usefulness of the manual!

Is there some set of rules applying to manual writing?
Is there anything like a tutorial or guidelines?
Please, speak to me
Thanks

piatkow

1:09 pm on Nov 2, 2007 (gmt 0)

WebmasterWorld Senior Member 10+ Year Member Top Contributors Of The Month



Start by determining the level of knowledge expected of the reader. Will the manual be for total beginners or will some underlying technical knowledge be assumed?

State those assumptions in the preface and stick to them.

draggar

1:55 pm on Nov 2, 2007 (gmt 0)

10+ Year Member



I would say look at the intended reader (as stated above) but write the manual one or two levels below them.

Manuals change hands plus the business manager may want it but some someone else may be handed the manual to manage the site.

henry0

2:28 pm on Nov 2, 2007 (gmt 0)

WebmasterWorld Senior Member 10+ Year Member



Thanks all.
your suggestions make sense.

vincevincevince

2:37 pm on Nov 2, 2007 (gmt 0)

WebmasterWorld Senior Member 10+ Year Member



Make a list of all possible tasks which the owner might need to perform. Tasks on the website that is, not in general. Get a screen recorder (there are free ones around) and execute each possible task, one at a time with the recorder running.

Stop; go out, do whatever.

Now, play back that video extra slow, pausing every time you do something, and write that thing down. Add screenshots of every key stage and the layout of every menu. Every time you give something a name, include a picture of it; no discussing the 'customer administration menu' without a picture nearby.

Provide a section entitled 'how to' which lists all the key tasks with references.

How to:
- Delete a client from the mailing list (4)
- Ask henry0 for his home phone number (6)
- Rewire a plug (9,10)

In the index, do the same thing but almost backwards:
- Clients: (4-12)
. - Deleting (4)
. - Exporting (11)
- Henry0 (13, p.14)
. - Home phone (13)
. - Bank details (14)

Finally, get someone capable of the job, and preferably someone who's not familiar with your system, to proof read it.

engine

3:01 pm on Nov 2, 2007 (gmt 0)

WebmasterWorld Administrator 10+ Year Member Top Contributors Of The Month



I once wrote an office manual covering every aspect of the office operations.

If I wrote down how I thought it should be done, I missed out some real obvious things, such as scroll down the screen for the answer. I found it much easier to shadow current members of staff to see how they operated the equipment and systems.

So, what I was indicating is to get someone less familiar to press the keys and operate the system, and as vvv said, write it all down.

Pictures, screen shots and sample forms help, too.

Once done, run through it again to check it.

It really is worth the effort in the end.

henry0

3:03 pm on Nov 2, 2007 (gmt 0)

WebmasterWorld Senior Member 10+ Year Member



VinceVinceVince Positively excellent!
I will follow that route and keep in mind previous posts.
The screen recorder is a great addition.
<edit>
Thanks engine did not see your post while typing
</edit>