| Nick Shubin | ||||
| Home | Articles | Photos | Publications | Site Map |
Nick Shubin
solve software problems on the Mac OS X platform
(basic ideas are applicable to other operating systems)
May 7, 2009
Commonly, when you ask for help or report a bug, you should give a technical support engineer some details on the problem. Do this in your first e-mail (forum message, telephone call, etc.). The rest can be requested from you later and depends on the problem. If in your request for help you write something like "I cannot print" or "It doesn't work", you delay your problem solution. By giving no details, you make your correspondence two steps longer (one message to ask you for details and one yours to reply).
Usually it is reasonable to quit and re-open the program and your document (except the case when you cannot save it). Then repeat your actions in the same order. If the problem persists, the tech support can ask you for an instruction on how to reproduce it. Be ready to describe carefully what you did.
Before new attempts, make sure that all open documents have been saved. When a program works improperly, it can destroy or loose open document(s). If you have an unsaved document, save it under a new name (File > Save As) to keep the last working copy.
Begin the sequence of steps from scratch. For example, if a pasted license code wasn't accepted, don't paste the content of the clipboard again. Probably not all the characters have been copied and the clipboard contains an incomplete code. Copy the code again before a new attempt to paste it.
Warning! In this section you were offered to repeat the problem. In some cases it's better not to do this but consult with a professional because your actions can make things even worse. I mean problems with the operating system or system utilities, or problems with the hardware.
Check the version of the software. If you are using not the latest version, run the update. In the last version the problem may be fixed. Remember that the software developers don't like bug reports concerned old versions.
The update function can be located in the main program menu (e.g., "Swift Publisher > Check for Updates…"), or under the Help menu (like in TextWrangler: "Help > Check for Update"), or in the program preferences (Firefox has the Update section in the Advanced settings in the preferences). Alternatively, go to the developer's web site to download and install the update manually.
See if the program documentation (or web site) has the "troubleshooting" or "known issues" sections. Maybe they contain a solution for your problem. Other users may have been discussed your problem in one of software forums and a workaround was found. Run a search. Note that if the program communicates with an external device (printer, scanner, CD/DVD burner, etc.), learn its documentation too. Make sure that the drivers of these devices are up-to-date.
Interestingly, the Bug Report Form on the Apple Developer Connection web site (http://developer.apple.com/bugreporter/bugrptform.html) has the "Workaround" section. Apple receives solutions from users for free, but collects fee giving workarounds to users:
"Please note: Workarounds are considered to be Technical Support incidents. You must purchase Technical Support if you would like to receive a workaround. …"
I find much better that users share their workarounds with others somewhere in public places (forums, articles, etc.).
Normally, software developers request necessary information providing a standard form for bug reports. If don't, use the list given below.
Provide this information in your bug report:
1) Tell what you did, what you expected to happen and what actually happened.
2) The name and version of the software that doesn't work.
3) The version of Mac OS X installed on your computer.
4) Steps to reproduce the problem.
5) Provide the simplest sample content (document, image, data base, etc.) that can be used to reproduce the problem.
6) Take screen shots of dialog boxes, property panels, document views that can relate to the problem.
7) Take screen shots of error and warning message boxes.
Tech support can ask you for additional information. Here is described where it can be found.
Choose the About… item under the program menu (e.g., Swift Publisher > About Swift Publisher).
Another place where you can find the version number is Finder. Select the application and choose File > Get Info (Cmd-I) in Finder's menu.
Select Apple in the menu bar and choose "About This Mac".
The information will be displayed in the "About This Mac" dialog box.
Open the Apple menu and select "About This Mac". Click the "More Info" button to open the System Profiler. In the System Profiler's menu, choose File > Save.
Applications can send messages to system logs as well as create own log files.
To preview logs stored in the standard folders ("/Library/Logs" and "~/Library/Logs"), use the Console.app application. Open the Console application located in the /Applications/Utilities/ folder. Click the "Show Log List" tool bar button to open the list on the side panel. Here you can choose a log.
To save the displayed log, choose "File > Save a Copy As" in the menu. Save logs after the problem has repeated. In some logs (e.g. Console log), programs continuously add new messages and delete earlier ones. Don't forget to provide your log with a description.
Console log (is used in most troubleshooting cases)
Choose "File > Open Console Log" in the Console.app menu. Then choose "File > Save a Copy As".
Crash log (is used after a program crashed)
A crash log is displayed in the crash reporter window after an application crashes (quits unexpectedly).
There are several ways to get the crash log:
Installer log (is used when the installation wasn't successful)
Installer.app is the system utility that opens the *.pkg files by default. When the Installer.app is running, choose Window > Log (Cmd-L) in the menu bar to open the log window. Its toolbar lets you change the log detail level. Choose File > Save to save the log.
Screen shots
To take a shot of the entire screen, press Cmd-Shift-3. To select particular area, press Cmd-Shift-4. "Picture 1" graphic file is created on your Desktop. When you take a sequence of shots, the number in the file name increases.
Some users decrease the file size by decreasing the picture quality. It's a mistake because the picture looses details. If your mail software has an option to change the image size or quality, choose the actual size or compress the image before emailing it.
Screencasts
Screencasts are useful for demonstration incorrect work of a program. In some cases, a screencast is better than a textual problem description supplied with screen shots.
To capture the screen, you can use one of free or commercial programs:
Capture Me (free)
http://www.chimoosoft.com/products/captureme/
Copernicus (free)
http://www.danicsoft.com/projects/copernicus/
ScreenFlow
http://www.telestream.net/screen-flow/overview.htm
Snapz Pro X
http://www.ambrosiasw.com/utilities/snapzprox/
A problem may happen when you work with particular data (document, image, data base, etc.). This content can be used to reproduce a bug or understand what's wrong.
Well prepared content should contain as few unnecessary information as possible. For example, you have a data base containing thousands records. Create its copy and delete most records in the copy. If the problem repeats, attach the shorter database to your bag report. Possibly, the problem is caused by only one specific record, this record should remain in your sample data base. The same thing for multi-page documents.
Related articles:
How to Report Bugs Effectively, by Simon Tatham
http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
Painless Bug Tracking,
by Joel Spolsky
http://www.joelonsoftware.com/articles/fog0000000029.html
© 2016 Nick Shubin. All rights reserved.