On-Line User Documentation Made Easy by Scott Orr

The last and most tedious task (for me anyway) in delivering expert applications is user documentation. It seems like many years ago when companies would actually have technical writers on staff and they would document everything to the Nth degree. Now businesses are run lean (too lean in many cases) and it’s up to the programmer to create user documentation if any is created at all. This article will show a very simple way to create on-line user documentation that helps reduce user error and frequent calls to IT.
First, let’s start by showing a typical user screen:

What we want to focus on is on the top right corner of the screen:
In our Provisioncy software package we show the abbreviation for whatever application the user happens to be in. In this case it’s Human Resources (HR). What’s significant about it is the underlining. When a user sees that they know clicking the ‘HR’ will open a new window that will display user documentation for this screen. On our end all we need to do is:
1. Create a PDF with the documentation naming it the same as the program name and place it in our ‘helptext’ folder. In this case it would be ‘emp1.pdf’.
2. Include code in the banner that contains a hyperlink to execute when the letters are clicked on.
Now for the code in our in the ‘banner.php’ file which is included in every program that displays data:
Before the HTML code we use:

 

1. $sarr = explode(‘/’,$_SERVER[‘PHP_SELF’]); Retrieve the program currently being executed from the internal Server data. In this case the value is /infiniumhr/emp1.php. We use the ‘explode’ code to place the values within the slashes into an array
2. $filen = $sarr[2]; Place the value ‘emp1.php’ in the variable $filen
3. $dot = explode(‘.’,$filen); Now create an array with the value of both sides of the ‘.’ in $filen
4. $file = $dot[0]; The name of the program is now in $file
5. print “<td width=’10%’ align=right bordercolor=#083C73 bgcolor=white>”;

unset($href);

if (file_exists(“../helptext/$file.pdf”)) {

$href = “<a href=’../helptext/showdoc.php’ target=’_blank’>”;}

print “<p align=’right’><font size=4 color=green>$href<b>$useapp</b></font></td>”;

Now our HTML with embedded PHP code says if a file with the name emp1.pdf exists in the ‘helptext’ folder, make the variable ‘$useapp’ a hyperlink which executes PHP code in ‘showdoc.php’. The variable ‘$useapp’ contains the value ‘HR’ as shown on the screen print.

 

The ‘showdoc.php’ script is shown below. It effectively looks at the ‘referring’ program (emp1.php) and prints the PDF in a new window. You could eliminate the first 5 lines of code by passing the file name in the hyperlink and then use only the 2 print statements.
<?
$referer = $_SERVER[‘REFERER’];
$sarr = explode(‘/’,$referer);
$filen = $sarr[4];
$dot = explode(‘.’,$filen);
$file = $dot[0];

print “<object data=’$file.pdf’ type=’application/pdf’ width=’100%’ height=’100%’>”;
print “</object>”;
?>

Once you have this code in place, all you need to do going forward is create the PDF document for any program and place it in the ‘helptext’ folder. This existing code will do the rest!
Finally, here is the PDF that the user ultimately sees:

Leave a Reply

Your email address will not be published. Required fields are marked *