0

What should the table of contents look like? How would you organize it? The table of contents and how it's organized would be helpful in knowing how to write the documention for a program for a large company. Do you go button by button or UI element from left to right, or is there some other way you can organize it?

Let's assume it's made for users.

2 Answers 2

1

The key question is, who is the audience for the documentation?

Possible answers: people who are trying to learn how to accomplish one of several tasks, the testers performing quality assurance testing, the lawyers who are establishing boundaries about the software does, and prospective buyers who want to know if the software provides specific functionality.

Each of these groups (and others) would benefit from a document tailored to their needs. Most users of a large, complex package like Microsoft Word use only a small fraction of the features. If I do not use footnoting in my work, I do not want to wade through a detailed explanation of the feature in order to find out how to do the thing that I really want to do.

The next problem is cost. Each of these tailored documents will cost money to create and more money to maintain. It is unlikely that every audience can or will be served. Too often, this means that the bare minimum of documentation is produced by technical writers who are not given the time or resources to do anything more than enumerate the buttons and UI elements.

2

Any software user guide will be a complex document no matter how you create it. By far the best option these days is to create it as an e-book style PDF complete with a comprehensive (three-levels) table of contents for ease of navigation and rapid access to any written content.

However, since the advent of really good and easy-to-use screen capture and video editing software, combining an e-book along with clickable hyperlinks or static links to a video library playlist makes this a breeze.

Using three of the world’s best software applications to accomplish this is easier than you might think. The addition of a google account and a YouTube creator’s account makes all this possible.

Speech recognition software enables seriously fast compilation of any document, the optional additions of Grammarly and Snagit complete the list of items needed to create any style of professional workbook, workshop manual or user guide.

The learning curve to do all this efficiently, professionally, and for the lowest possible cost is a steep one. But well worth the effort. The needs of the end-user are the critical criteria that dictate specifically how your document must be created and presented.

You will gain immediate feedback from your user guides, both the written content and the linked video content, from the very second that someone puts them into practice in real-time.

If you’ve made any blunders anywhere, they will be rapidly pointed out to you! Then comes the time for some very quick modifications to your user guide content and a quick republish and the job is done.

If you are producing hardcopy documentation then you will need to use a print on demand service as your users require it, and as a paid-for version, because if you produce hardcopy as a stock item it is virtually impossible to rectify any issues once print production has started and filters into any distribution network. Your stock will become unusable and unsaleable and your business reputation and your bank balance will be permanently tarnished.

An e-book, on the other hand, does not suffer from the above ailments and can be modified as required and back into circulation the same day whether product delivery is by a link in an email or a website download location.

Video content produced as supporting content for the e-book can also be very rapidly correctly reproduced and back into circulation the same day.

I find that software user guides are best produced as a multi-video content displayed playlist, and also with a comprehensive and well-detailed table of contents for ease of user navigation throughout the contents.

For example; if it takes two hours to go through a particular software showing all the functions, it’s better to separate all those functions into separate videos.

Your goal should be to produce videos of say 15 minutes in length for the comfort of user absorption or of a duration enough to cover the particular software functions that can be broken down or segmented.

The days of filling a hardcopy book with hundreds of screenshots (very time-consuming to create) of software demonstrations are over.

I’ve produced all manner of user guides, workbooks and workshop manuals for everything from software to mechanical items over the past 20 years. It’s standard practice for me to offer everything in all formats.

The e-book with linked video content wins hands down every time these days and is almost always chosen as the preferred medium for accepting complex or tedious information.

When you ask your end-users what they want, and how they want it delivered, the response is usually rapid and precise.

An ‘ask campaign’ works very well for any informational product.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.