Context Sensitive Help - PHP Class

Question

All,

I have a PHP Web application built using Zend Framework and MVC with MySQL database. I plan to implement Context-Sensitive Help for the application.. I did my research but I didn't find any good pointers on how to achieve this.

Can someone point me to a book or a nice reference with example that does this? I see this implemented in major insurance company websites and other Web 2.0 sites.. How do they all do that?

Thanks

Answer 1

Examples would indeed help, but I guess they give every screen in the app a unique ID and store the related help in a database linked by this ID. That's how I would do it anyway :p.

BTW One step further would be to link screen areas in the same manner (ie. give a fieldset or even separate fields a unique ID, which can then be used as lookup key to retrieve the relevant help information).

Answer 2

Consider using a specialized application (for example a Wiki) for creating and maintaining the documentation, and linking to single pages in the wiki from within your application. I am planning something similar and I'm quite sure this is a very good way to go.

If you use a Wiki, you could have your help function (whatever that will look like) point to wiki pages like documentation:installation:4_creating_databases and use a customized template to display the wiki page in a popup window, for example.

As for finding the right application to maintain the documentation, maybe this question helps: Good documentation software and maybe also minimalistic tools for developer documentation (slightly different focus but very good recommendations).

Answer 3

I did this with a simple wiki using PHPMarkdown syntax.

There was a whole lot more additional related documentation stored in the wiki, so context Help pages started with the prefix 'Help ' in the title. This was useful because it allowed help pages to refer to other business process documentation and to save me repeating myself in several places (grin).

In the layout script, I added a menu item "Help" which was rendered via a helper

class Zend_View_Helper_ContextHelp extends Zend_View_Helper_Abstract
{
    //-------------------------------------------------------------------------
    /*! \brief Context sensitive help: links to wiki page
    */
    function contextHelp( $title = 'Help' )
    {
        $controller = Zend_Controller_Front::getInstance();
        $request = $controller->getRequest();
        $page = 'Help ' . ucfirst( $request->getControllerName() );
        if ($request->getActionName() != 'index') $page .= ' ' . ucfirst( $request->getActionName() );
        return $this->view->url( array( 'controller' => 'manual', 'action' => 'index', 'page' => $page ), null, true );
    }
}

so this link was visible in the top right corner of every page.

For the customer/edit action the help page would be 'Help Customer Edit'. A lot of my pages had help information and links already embedded in them: so form fields had descriptions advising on correct content with examples, some with links to wiki pages for more detail or extended examples.

The wiki database schema is real simple

CREATE TABLE `manual` (
  `id` mediumint(9) NOT NULL AUTO_INCREMENT COMMENT 'Unique manual identifier',
  `title` varchar(40) NOT NULL DEFAULT '' COMMENT 'Short title of this page',
  `content` text NOT NULL COMMENT 'Content of the page. (wiki format)',
  `user_id` mediumint(9) NOT NULL DEFAULT '0' COMMENT 'The related user',
  `last_modified` datetime NOT NULL DEFAULT '0000-00-00 00:00:00' COMMENT 'Date and time this record was last changed',
  PRIMARY KEY (`id`),
  KEY `user_id` (`user_id`),
  KEY `title` (`title`),
  KEY `last_modified` (`last_modified`)
) ENGINE=MyISAM  DEFAULT CHARSET=utf8 COMMENT='Franchise Manual' AUTO_INCREMENT=50 ;

Happy to post the Manual model and controller (plus a few supporting helpers) but they are a bit long... let me know if you are interested and I'll make a blog post and link to it from here.