Sample Technical Guide
- 1. sample technical guide.doc © 2010 Lisa Lugo Introduction to this sample document I wrote this technical guide for an online classroom that my company created. The purpose of this guide was to document all of the application’s technical details, and provide trouble- shooting solutions. The audience for the document was the helpdesk. The following sample document includes the complete Table of Contents from the original document, to illustrate the level of detail the guide contained. Next, I included the Introduction and Overview sections so the reader understands what the Online Classroom looked like. I then provide a sample of one section so the reader can become familiar with my writing style. All references to proprietary information have been removed.
- 2. sample technical guide.doc © 2010 Lisa Lugo Table of Contents Below is the complete Table of Contents for the technical guide: Introduction ......................................................................................................................................1 Overview of the Classroom ................................................................................................................1 1. Initial Setup....................................................................................................................................2 Technical Specifications................................................................................................................... 2 Display Resolution............................................................................................................................ 3 Setup Wizard.................................................................................................................................... 3 Plugins downloaded............................................................................................................ 3 Browser Settings.............................................................................................................................. 3 Internet Explorer................................................................................................................. 4 Netscape Version 4.7.......................................................................................................... 4 America Online ................................................................................................................... 4 Firewalls........................................................................................................................................... 5 Bandwidth........................................................................................................................................ 5 2. VOIP ..............................................................................................................................................5 No Sound.......................................................................................................................................... 6 Poor Sound Quality.......................................................................................................................... 7 User must press CTRL to speak........................................................................................................ 8 Echoes.............................................................................................................................................. 8 No connection.................................................................................................................................. 9 3. Synchronization .............................................................................................................................9 Cannot see other people’s annotation.......................................................................................... 10 Cannot chat.................................................................................................................................... 10 Classroom frozen ........................................................................................................................... 10 4. Application Sharing ......................................................................................................................11 Cannot show application ............................................................................................................... 11 Application not sized correctly in content window....................................................................... 12 Content window has a strip of “noise” by the application............................................................ 12 Student cannot share the application ........................................................................................... 12 5. Content Management ..................................................................................................................12 Content Pushing............................................................................................................................. 12 Cannot see slides ........................................................................................................................... 13 Cannot annotate over a slide......................................................................................................... 13 Content Uploads ............................................................................................................................ 13 Error Message during upload - Failed criteria ............................................................................... 14 File content does not fit properly in the window (too large, too small). ...................................... 14 Cannot load a website ................................................................................................................... 14 HTML files are not displaying all graphics...................................................................................... 14 6. Miscellaneous ..............................................................................................................................16 Login issues .................................................................................................................................... 16 Cannot login...................................................................................................................... 16 Logged out ok, but can’t log back in................................................................................. 16 Dropped connection ...................................................................................................................... 16
- 3. Online Classroom Technical Guide sample technical guide.doc Page 1 of 4 © 2010 Lisa Lugo What follows is a sample of three sections in the guide. Introduction XYZ Company’s Online Classroom is a “virtual meeting room” accessible over the Internet. It has an interactive whiteboard, two-way VOIP audio, two-way chat, and the ability to push and view content in a variety of formats including PowerPoint, JPG, GIF, HTML and live websites. The Online Classroom is a fully web-based, thin-client architecture. Two-way, real-time interaction between multiple participants is made possible through our “Server” component. VOIP is provided using xxxx from xxxx. Content files are stored on the XYZ Company server. Most users experience little or no difficulties in accessing and using the Classroom. For those who do have problems, the majority of these occur the first time they access the Classroom. However, it is important to be familiar with, and be able to correct, any problems that may occur. This manual provides the information needed to troubleshoot the typical problems encountered when installing or using the Online Classroom. When a user calls to report a problem, use this manual to help diagnose and correct the situation. If you are unsuccessful, you may contact XYZ Company at (111) 111-1111 or email support@xyzco.xxx for assistance. Please do NOT distribute this phone number to your users. It is for your designated contact person only.
- 4. Online Classroom Technical Guide sample technical guide.doc Page 2 of 4 © 2010 Lisa Lugo Overview of the Classroom The main areas of the Online Classroom are labeled in the diagram below, and include the following: Whiteboard/Content Window Drawing Tools Chat Area Participants Attendance Box Space for company logo and instructor photo Audio Controls Instructor Controls Figure 1. Online Classroom
- 5. Online Classroom Technical Guide sample technical guide.doc Page 3 of 4 © 2010 Lisa Lugo Content Uploads The Classroom allows instructors to upload content in any of the following formats: HTML JPG GIF ZIP Video files (QuickTime, Real, or Windows Media – must be zipped before upload) Live URLs Zip files are a special case – instructors can upload multiple files at once by compressing them into a zip file. Once uploaded, our system automatically uncompresses the zip file and displays each file as a separate entry in the Slide List. Zip files can be used to upload not only HTML, JPG and GIF, but also QuickTime videos. Currently there is a limit of 10MB per file uploaded. This amount can be increased on a request basis. To upload a file, the instructor clicks the “Edit Slides” button, assigns the file a name, then either types in the URL to be loaded, or clicks “Browse” to upload a file from the hard disk. Error Message during upload - Failed criteria Description: Upon uploading content the user receives a message saying “Failed criteria”. Solution: This error can occur for several different reasons: Bad file name. The file name cannot contain any special characters or spaces. The Lesson List Manager will only accept alphanumeric characters and the underscore _. Using special characters, or spaces, will result in an error message “Failed Criteria”. Incorrect file type. The file being uploaded is not one of the supported types (jpg, gif or html). Note that video files must be compressed into a zip file before they can be uploaded. Selected wrong file type (zip files only). The user did not check the correct box for the type of files being uploaded – check “HTML Files” if uploading HTML, or “All Files” for jpg and gif files. If the wrong box is checked the upload will fail. Missing file name. The user must always type in a name for the file. In the case of zip files, this name will not be used, but the upload will not complete if no name is entered. HTML files are not displaying all graphics. HTML files often include GIF files for graphical components. These files may be referenced in the HTML code by their full filepath, which often is a separate
- 6. Online Classroom Technical Guide sample technical guide.doc Page 4 of 4 © 2010 Lisa Lugo subdirectory. When the HTML file (and associated gifs) are uploaded, the filepath is no longer valid. To correct this, the HTML code must be modified to correct the location of the GIF files. Specifically, all references to subdirectories in the HTML file should be replaced with dot-slash (./) The easiest way to do this is as follows: 1) Open the HTML source code. 2) Search for src= This will bring you to the first reference to a .gif file in a subdirectory. 3) Edit the reference so that the name of the subdirectory is replaced by ./ (i.e., dot-slash). 4) Repeat this for each src=. 5) When done, save the file to a new name (so you don’t overwrite the original). Example In this example, there are 3 GIF files being referenced: abc.gif, bar.gif, and glass.gif. All 3 files are in a subdirectory called “Images.” Original HTML File <TBODY> <TR vAlign=top> <TD vAlign=top><A href="http://dev.xyz.com/"><IMG border=0 src="Images/abc.gif"></A></TD> <TD align=right width="100%"> <TABLE border=0 cellPadding=0 cellSpacing=0 width="100%" valign="top"> <TBODY> <TR> <TD width=300><IMG height=28 src="Images/bar.gif" width=1></TD> <TD><A href="http://dev.xyz.com/master/welcome/help/"><IMG border=0 height=17 src="Images/glass.gif" width=20></A></TD> For this HTML file to properly call the 3 GIF files when it’s uploaded, any reference to the “Images” subdirectory must be removed and replaced with ./, so that the code looks like the following: Revised HTML file <TBODY> <TR vAlign=top> <TD vAlign=top><A href="http://dev.xyz.com/"><IMG border=0 src="./abc.gif"></A></TD> <TD align=right width="100%"> <TABLE border=0 cellPadding=0 cellSpacing=0 width="100%" valign="top"> <TBODY> <TR> <TD width=300><IMG height=28 src="./bar.gif"width=1></TD> <TD><A href="http://dev.xyz.com/master/welcome/help/"><IMG border=0 height=17 src="./glass.gif" width=20></A></TD>