Objective Technical Report Regarding The Creation Of Help Systems At Kelley Computing

Author: Edward Kelley
Lead Software Developer/Engineer
Kelley Computing
www.kelleycomputing.net

Objective Technical Report Regarding The Creation Of Help Systems At Kelley Computing

Author: Edward Kelley
Lead Software Developer/Engineer
Kelley Computing
www.kelleycomputing.net

Created in sync with:
Mt. Hood Community College
Writing 227 – Web Based

Instructors:
Lynn Darroch and Jodie Marion

This is the official transcript detailing a proposal for methodologies and procedures to follow when composing help system for Kelley Computing software.  

Executive Summary

	There are currently no documented examples, reports, or proposals that detail how to create help guides for Kelley Computing software products.  This report will serve as a guide, and reference manual to ease the strain of those documents’ creation.  The ideas presented are only helpful suggestions, and are not bound to the methods detailed here.
	After reading this report, the reader will have a better understanding of the processes necessary to provide the integral help manual, which is required by most software users.  As stated above, this paper is not meant to be a list of instructions, but a helpful and intuitive look into making a job easier to do.  These are merely suggestions to lead all readers in the right direction.
	Recommendations on creating help manuals for the company are documented here, as a source for current, or perspective employees.  This reflects greatly upon us as a company, as it provides the means necessary to organize creation of these documents.  Leading the development team on their quests assists all employees positively. 
	Section one starts off by giving proposed methods of implementation, reasons for, and hints to use when creating help, whether it be a guide, online manual, or in-program help system.  It explains objectives, proposed solutions, and methods of attaining those goals.  Recommendations are given based upon previous experiences with the topics.  The second section details the process of creation.  This includes references to other resources on the subjects, as well as a walk-through of the current procedures required.  This can also serve as a quick-reference for the developer in the future.
	Certain background skills are needed o accomplish many of the tasks detailed here.  Although most developers here use similar languages, with varying experience, there are certain requirements for accomplishing things.  Programming experience, both with Objective-C, HTML (or the authoring equivalent) and web coding.  The processes should be laid out well enough to guide even the most inexperienced engineer through a simple implementation.
	Communications channels are important for getting developers and users in touch.  This must be integrated into current program design, and procured for future use.  This paper will be a valuable resource for this company.

Table of Contents

Executive Summary
	• Summarization of the report

Part I
Section 1 – Problems									p. 6
	• Broken computers not able to be repaired easily
	• Software manuals are not straight forward enough
	• Software manuals are not easily and quickly reproducible
	• Lack of detail in manuals
	• Bugs and glitches not being reported
	• Advanced users need more information about program operations
Section 2 – Objectives								p. 7
	• Develop instructions and techniques for manual creation
	• Help others to repair computers easily, and effectively
	• Give future employees something to reference when creating their documentation
Section 3 – Solution									p. 8
	• Program usage manuals
	• On-line help systems
	• In-program help
• Steps to implement the above easily
Section 4 – Method									p. 9
	Steps
		• Using this document as a practical demonstration
		• Integrating this program into project routines
	Resources required
		• Descriptions of company resources, and considerations required
		• Qualification recommendations 
		• Overview of toll on developer
Schedule
		• Finishing guides in a timely manner
		• Description of how this report can aid in its expedition
		• Managing  projects when on a deadline

Cost
		• How these methodologies solve money problems
		• Keeping costs low

Part II
Section 5 - Help manual									p. 10
	Ideas for composition concepts and theory
		•  Which deployment format is best?
		• What do users look for in a help manual?
		• How can we shorten this process?
		• Examples of current procedures used
	Importance of stressing a readable design in implementation
		• Organization of information
• Placement of graphics
	Composing help manual templates
		• Importance of re-use, and its implications
		• Sources for materials
Section 6 - In-program manual								p. 12
	Reasons for implementing in-program help
		• Why is this the most consulted?
		• What does this cost the company?
		• How time consuming is the integrating into production software titles?
	Re-using manual content and coordinating change
		• Importance of re-use, and its implications
		• Sources for materials
Section 7 - Online manual								p. 13
	Concepts, benefits, and implementations of online help systems
		• Why do we want to make help so available?
		• What are the costs incurred on developers?
		• Who uses online help?
	Implementing your own online help guide
		• Re-using information from user guides
		• Composing web pages
		• Demonstrations of online help composition
Section 8 - Communications channel							p. 14
	Keeping connected with the user
		• How connected are we?
		• Do we know what most customers want?
		• What do we do in the event of bug emergencies?
	Developing and re-using online bug tracking systems.
		• Re-using information from user guides
		• Creating web pages for user reports based on templates
	Integrating in-program bug communications
		• Investigating the current methods of communication
		• Implementation and examples for construction
		• Creating a template for this process
Works Cited									p. 15

Part I

Section 1
The Problem

	There is a lack of documentation included with the current line of Kelley Computing software.  This means that the users are handicapped, and without the necessary skills essential to the correct usage of our software.  This is unfortunate, but the case - due to the company’s small numbers, and limited time for development.  An easy-to-use, reliable help procedure is not given for most of the company’s titles.  The instructions provided are many times plain text documents with only the basic program usage procedures outlined.  
	Being in the Apple Macintosh computer repair field for 5 years now, I have seen the need for assistive programs in the field, especially in the system repair and diagnostic utilities area.  This has motivated me to create this company, in the hopes to establish myself as an expert programmer in the field.  I have many years of experience, and know that the most common problem facing computer users is the lack of information, misunderstanding of, or inability to understand the communications presented with software. That, and the fact that the developers of this software are not able to clearly and effectively receive communications on a well-established medium, and the same is not provided the user.  We need to correct this, for the success of the company.
A good idea of what techniques to use when composing strong, un-obtuse manuals has not currently been established in the company.  Many times, the release of a software title will be the most stable build, with many help guides left unchanged from previous versions.  There is no template system available, and things must be created from scratch for each new title created. This intrudes on the development of intuitive, creative software, and inhibits developer productivity.  
	The developer of the software needs to be in contact with the user.  There is currently an option for users to write to the software company through a guestbook page on our website, but the volume of e-mail that comes through that channel makes it difficult to channel the different project requests and memos to the respective developer.  This will be integral to the company’s success in the future, as we expand, and must make changes quickly to evolve and survive in today’s world.

Section 2
Objectives

	In regards to this first project, the main objective is to assist the software users attempting to repair their machines by using the “unArchive” software produced by Kelley Computing.  Although this software is still beta release, I feel that this would be an opportune time to develop strategies, and this beta title will be a good “experimental” starting point.  
	This software allows users to “unArchive” a failed installation of Mac OS X, where the user’s home directories, and other system files and settings are moved, and made almost un-accessible.  That occurs when the user attempts to re-install Mac OS X, and certain factors cause the installation to halt (crash).  This results in an un-bootable computer system, leaving the user high-and-dry.  The software we are dealing with restores these systems to the condition previous to the disaster.  Because of the complexity of this software, it’s use must generally be performed by experienced service technicians.  At this point in time, even for those experienced enough to understand what the software does, the operations seem difficult, and there are times that the user can misidentify the problem (where this software may be helpful, but only with other modifications or procedures performed).  The procedures and techniques outlined in the report will give us the power back to the developers by giving the user clear, concise information on use, easing the strain on our support systems, and making the entire process more enjoyable for all.
	Developing a strategy for the easy creation of these articles will make life better for Kelley Computing employees, and other developers, when expanding services, or creating new software for the company.  This will lower employee-training time, by being able to provide easy to use templates, avoiding work that would have to normally be re-produced.
	Current bugs are only reported on the company’s support pages on the Internet.  Having this information more readily available in user help guides, online, and other options for this information’s delivery, will be planned for, and developed.  
	Making links from within our programs, leading to the company’s support site will ease the retrieval of knowledge for the user.  This can be accomplished by using an in-program help system, which will also include the majority of information contained in the user guide, and that currently available on the support site. We will add this to unArchive first, and then proceed to develop this for others (not included in initial report).

Section 3
Proposed Solution

	I will document the procedures necessary for creating a user help guide for my software, as well as my recommendations for implementation in a technical report.  This will also detail the steps necessary to add help-guide functionality inside of the software.  It will be accompanied by information regarding the composition of online help documents and other information pertinent to user-developer interactions.
	The program usage manual will recommend methods, and give examples on how to create manuals easily.  This will include conceptual information, easing the creation of these documents for other titles.  I will also save some kind of help manual template, speeding the process up immensely.  
My report will provide detailed information on how to present content dynamically online.  This includes posting bug notifications, and creating systems for relaying specific program information to the correct destinations.  Programmers will receive information about the program subject that is pertinent, allowing them to sort, and organize this information more easily.
We do not currently offer in-program help.  This assistance is available in all successful software programs, and is necessary for ours.  I do not currently know exactly how to develop these systems.  The topic will be researched (the research will be documented as well), as I know the sources of the information, but have not investigated the syntax.  This will provide an opportunity for me to document the retrieval of something outside of the knowledge I already possess, making techniques available to future or prospective employees.

Section 4
The Method

I will develop a program manual for unArchive, that includes graphical content, easing the use of the software.  This will be documented, and involve generic templates being made, for the future ease-of-creation that is necessary in a fast-paced development situation such as ours.  This will also help future programmers joining our mission, by giving them a format, and guidelines for creation, keeping things uniform across the board.  These templates will be available on the company server for download to employees only.
The technical report will display the ease of use with the Internet as a deployment medium.  This is quickly becoming the most effective way of communication, and it encompasses everything that the future holds for our company.  The digital mainstream has already been created. We need to harness its power.  Processes used will be detailed for ease of reproduction, and I will make a template for its exploitation.  We will also look at other possibilities for this operation.
Although the time frame for this project is defined, the same will not be the case in the future.  This may put certain restrictions on our developers’ creativity and freedoms for this beta experience, but we will work to maintain any boundaries, and cooperate with deadlines in the name of good practice.

From the date of this project beginning, the schedule should be as follows:

Week 1: Initial help structure an design contemplation
			Week 2: Rough draft of main help documentation	
			Week 3: In-program and online help integration, and testing
			Week 4: Final touch up, and release of product
	
Having the right qualifications to be the compositor of this report is integral.  My studies in computer science have been going on for the majority of my life.  I have been certified in the field of computer repair for the last 5 years, and have the necessary knowledge for those tasks.  Developing programs for the Macintosh since the early to mid nineties has given me the experience necessary to be effective in the pursuit of this paper.  Kelley Computing was developed in the early 2000’s as a free software source. My mastery of the Internet, and the composition of web pages, eases the Internet deployment side of things. All of the software titles offered by Kelley Computing are mine, and I possess the most thorough understanding of their functionality.  Following the steps outlined in this project will be great for customers, and this company’s progression.

Part II

Section 5
Help Manual

Ideas for composition concepts and theory

	In this day and age of computer technology, things are becoming more and more complex.  Programs that used to be simple, and straightforward enough for use without consultation of a help guide or manual are few and far between.  This trend will not change in the future.  Certain procedures need to be described in great detail to the user, but at the same time, keeping things easy enough for quick retention and comprehension.  Users need to be able to get the answers that they need from help in the fastest way possible, but also provide and easy-to-read format that will keep the reader’s attention.  This guide will serve as a reference for the developer to use when creating these pieces.
	One of the most important things to think about in deployment of these guides is compatibility.  The customer must be able to read the documents that we are including, so putting them in the most universal format possible is recommended.  The default format for user guides should be Rich Text Format (.RTF).  This is currently useable on all Mac OS X systems, as Apple included the free application “Text Edit” which can read Rich Text files.  Another option would be Adobe System’s Portable Document Format (.PDF).  This is one of most universally recognized formats, and will also serve as a good medium for distribution of these guides.  In the examples that we will be working with, the Rich Text format will be used, but this preference really rests upon the developer’s shoulders.  Formatting decisions can be influenced by: document length, content, and targeted audiences.  The two options here are definitely not the only ones to choose from, and there are sure to be more formats in the future.

What do users look for in a help manual?

	Most users want an easy to read guide that will walk them through the necessary steps to use the software provided.  This can be accomplished by using layouts that promote quick search and retrieval of information, as well as acting as an easy read-through.  This can be accomplished by using chapter markers (in longer documents).  Consider providing a frequently asked questions section, and troubleshooting information.  Perhaps the greatest challenge facing a developer is that of learning styles.  People learn, and absorb information in differing ways, so providing readable content for all types of personalities is important in getting the message out to the customer.
	
How can this process be shortened?

Creating manuals for software can be time-consuming, and really, bother to the programmer.  This is why we are going to stress the importance of making templates for your work whenever possible.  These can be generic program templates (meant for any program), or program-specific (for a certain program).  This will help speed the process of updating, and creation in the future.  Currently, there is no way to create a good template in RTF or PDF formats (but these options do exist for HTML documents).  The current methodology for this practice is to create newer manuals from the one last released.  This is recommended, as the re-creation of this content can be very beleaguering.  Creating generic help manual templates is something that the company has been working on, and these should be available soon.  

Examples of current procedures used

The processes for this procedure as described below will be an example, not a requirement.  There are certain guidelines that will be stressed for ease of use, but the choices are the developer’s.
	All of the manuals composed at Kelley Computing have a certain loose format.  The title and version of the software title being presented must be listed at both the top and bottom of the page, along with the company’s main website URL, pointing to the specific program page listed.  This is important for formatting purposes, and is really your only restriction. 

Section 6
In-program Help Manual

Reasons for implementing in-program help

	Most users consult the documentation that is included with the application (because this has been the main method of distribution in the past).  More, and more often, it is becoming necessary for programmers to include in-program help.  This lets the user obtain the help guide from within the program itself (using a “Help” menu).  This seems (for most) to be the best way to give the customer quick access to help without having to leave the currently running program, or search for the information on disk.  Apple has made this process very easy, and that should be taken advantage of.  
	The main format of in-program help guides is HTML.  This is the language that comprises the majority of web pages being served on the Internet today.  The difference between HTML, and plain test is really just formatting, and it’s inclusion in the flat text file.  The help guides created for normal distribution can be seamlessly pasted into HTML documents, simplifying the creation process.

Re-using manual content and coordinating change

	It is recommended that developers use an HTML editor to create the manuals.  These programs simplify the procedures, by letting the developer create pages using a graphical user interface (GUI).  Programmers do not need to learn another language (if applicable) to write their help manuals in.  The recommended method of creation is for the developer to paste the normal Help guide into the in-program help.  This keeps things easy on our end, and simple for the customers, as there are no discrepancies between the different texts.
	Apple (Apple Computer, Inc.) has some of the best resources on learning how to implement help in your software.  Their instructions can be followed easily, and should be a valuable resource in the discovery, and shaping of ideas in the future.  O’Reilly (Davidson, James Duncan) has some of the best books in print for learning different techniques for application and other software development for Mac OS X.  He outlines the procedures necessary for the creation of user guides, and is the format that will be followed at Kelley Computing for the time being. 

 

Section 7
Online Help Manual

Concepts, benefits, and implementations of online help systems

	The Internet has become the world’s most valuable resource for accessing the widest variety of information in the shortest amount of time, and with the least effort expended.  This should be on thing that we, as computing professionals should take full advantage of.  The “Information Super-Highway” is in its adolescence, and therefore taking control of it is something that every professional should know.  Even though it may seem adequate to provide assistance to users both in document, and in-program forms, there is still great appeal to offering help to individuals in an easy to reach, highly available manner.  This can lead to more information being gathered about our software (which is available on the Internet only) without someone having to download it.  This will result in more informed users, and also, more questions being answered.
	Because the format of online content happens to be the same as that of the in-program manuals, we can use that as our source of information regarding help.  Since the in-program help then, in turn, inherits its content from our program usage/help manual, this gives us an easy way to cut the majority of replicated work out of this process.  In this sense, we can template the methods of delivery, further improving the program’s total construction time.
	As stated above, Internet users investigating our software can benefit greatly, and so can we. The customer will be more informed when browsing the manuals before use of the product.  If a current user of the software needs to get information, this can be offered online for global access.  Our customer can get the information they need in several places, and are less likely to ask a “Frequently Asked Question”, freeing up time for the developer to concentrate on more important tasks like engineering software.

Implementing your own online help guide

	As stated above, the re-use of our in-program help material is integral in the creation of the online help system.  The folder of documentation will be placed on the company page in the same structure as laid out for the in-program manual.  It is recommended that you compress this root help folder (named “Help”) into an archive.  The preferred archive format is a disk image (.DMG), as this stores data in a forked file system.  Other, more compatible formats (such as .ZIP and .TAR) can be used, but you must understand the formalities of each compression option.  All software programs should be thoroughly tested: even after final packaging is complete.

Section 8
Communications Channels

Keeping connected with the user

Currently, the company is not prepared to handle massive user input.  Although it is suiting at this time, the preparations needed must be considered in the work that is done today.  This forward thinking approach is integral to our success, as our current methods are not necessarily up to par. 

Developing and re-using online bug tracking systems

	There are currently bug reports on the Kelley Computing support pages (http://www.kelleycomputing.net/support), but there is no organized way for the user of software to get bug-report information to the developer quickly. The contact page at our main site serves as a multi-purpose contact point, and must be sorted from one account..  This can be more organized by leading users to post information about the programs from that product’s page.

Integrating in-program bug communications

	We do not currently have the functionality built into our software to allow live user communications, but it is possible.  This is the topic of a future (smaller) technical report, but will be discussed here in brief.  Software today has the ability to communicate back to a server on the internet to relay communications from and to the program, notifying the user of updates, bugs, and other things, and also enabling communications from the software back to the developer (crash reports, etc.).

Works Cited

Apple Computer, Inc. Introduction to Online Help 29 Oct. 2003. http://developer.apple.com/documentation/Cocoa/Conceptual/OnlineHelp/index.html.

Apple Computer, Inc. Introduction to Providing user Assistance With Apple Help (Revision; Preliminary). 28 June 2004.
	http://developer.apple.com/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/index.html

Davidson, James Duncan and Apple Computer, Inc.  Learning Cocoa with Objective-C. 2nd ed. Sebastopol: O’Reilly, 2002.

Rickards, Jordan.  Personal Interview.  15 Feb. 2005.