How can my system docs be more interactive?

Question

Perhaps if I make the my documentation better I could spend less time supporting developers and more time developing myself:

I develop a critical platform used by 10 other developers and 50 end users. The developers are of mixed ability ranging from domain-experts to relative beginners. Since I'm one of the people who know how the core platform works support requests from other developers usually go via me.

Our documentation is the usual sort of descriptive stuff any mature project will have: We have a large wiki containing details of all the usual operating procedures plus extensive API documentation.

Unfortunately it does not cater well for "how do I fix " type questions:

Would it be possible to make some interactive fault diagnostic documentation that puts users through a standardized fault-finding routine. The documentation would ask users a series of questions, and depending on the user's input would tell them what to do... it would be a very simple expert system, or possibly a documentation state-machine.

The idea would be to help newbies think more methodically about diagnosing faults in this complex system.

My question:

• Are there any free tools intended to implement this kind of user-experience? I'd rather not hand-roll this. There must be some kind of framework for interactive help & documentation.

• Has anybody implemented this kind of system before?

Thanks

Answer 1

Perhaps a wiki?

Answer 2

If you just wanted to have a flowchart/stat-machine thing where the user moves from the start point to a set of possible solutions by answering questions, then you could probably implement this as a set of wiki pages, where the possible responses to questions on one page are links to other pages.

This solution relies on being able to represent the answers to questions as links, which isn't going to work if the information is more form-like. For example, suppose one question is "What brand of graphics card do you have?" where the answer is one of 300 possible options. In this case it's going to be tiresome to create the links :)

Answer 3

If the developers are asking too many questions then I would suggest making them research the question themselves and come up with an answer, then double-check with you instead of encouraging them to ask you every time. It's much easier to ask somebody else than to find the answer yourself, but they're never going to learn if they don't look for themselves.

If the users are asking a lot of questions then you may need some user interface improvements. Try putting hints in the application itself at the top or bottom of the screen maybe.

For both groups of users a wiki can help.

Answer 4

• a FAQ in your wiki
• if an error happens too often, try preventing it or output a more useful error message (like "if this happens, the likely cause is that...)