More Related Content
Similar to Sample Technical Guide (20)
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>