indoiton - Design of New Documentation

Design of New Documentation

Your need

Do you have developed a new product or new software which needs user documentation such as manuals or online help?

My service

On the basis of a detailed target group analysis I can develop a user-friendly and cost-efficient documentation solution for your product – from the didactic concept to the detailed structure. If online help files or software demos are involved, a basic prototype is usually also part of the concept.

However, be warned: As a result of the consequent focus on your target group, the designed solution will most likely not be the solution that you would prefer yourself if you were using your product. This is because you are not part of the target group and have special prior knowledge that your clients do not have. Like a good suit, a good documentation solution cannot be tailored to everybody at the same time. The important thing is that it fits your clients. Only then your clients will be happy, and only then you will be happy, too.

As an option, I can also author and produce the designed documents of course, or I can assist your own staff to do so.

A lot of persons in charge wonder whether they need a documentation plan at all. Can't a professional writer just start writing and let the documentation "evolve"? Yes, he or she can, but it will always be the more expensive way and it will always take longer. Why?

▪

A lot of decisions have to be made along each project. You can make a decision as part of a prior concept, or you can make it "on the fly" when writing the text. Both takes the same time.
So, this far there is no gain by developing a prior documentation plan, but there is no loss in time and money either.

▪

A lot of decisions are mutually dependent. Therefore, some of the decisions will always have to be revised as part of the process.
If you are working on a plan, revising a decision is quick and costs nothing: All you have to do is change your mind. If you are working on the actual document however, revising a decision will be costly. You will have to change everything you have produced so far. The more you have written, the more it will cost.

Now guess what is safer, faster and more cost-effective...

A sound documentation plan does not have to be extensive, but it should at least answer the following questions:

▪	Needs of the target group What do your clients know already? How do they work? What are their main goals and tasks?

▪

Other imperative parameters
What fundamental restrictions must be taken into account, such as deadlines, budget, frequency of future updates, translation requirements. Does the documentation have to fit into a line of existing documents? In case of software: which operating system is used, which programming language is used, which browsers are available on the users' computers. In case of software on mobile devices or machine operator panels: what is the screen size, is there a mouse and a full-featured keyboard available?

▪	Media Will there be a printed manual (pdf) or context sensitive online help or both? What information goes into the manual and what information goes into online help?

▪	Help formats / context sensitive help calls Which help format will be used? Plain HTML or compiled help? Can context sensitive help calls be implemented? Who assigns help IDs: the programmer or the help author?

▪	Documents What documents will you provide? Will you put all information into one document or will you supply several manuals for specific purposes or user groups?

▪	Information types What types of information do your clients need? Basic conceptual information, reference information, step-by-step instructions? Do they need domain knowledge as well as specific application knowledge?

▪	Navigation What navigational devices will you provide within an online help? Where do you provide links / cross references, and where not?

▪	Structure What will be the structure of your document(s). Which chapters / topics will you provide?

▪	Production Which authoring tool do you choose? Can this tool handle all the languages you require today and in the foreseeable future?

As an option, a documentation plan may also comprise a sample layout and a basic prototype of an online help or software demo file.