I admit it: I don't know the InDesign Scripting DOM by heart, so I spend a lot of time browsing around in the ExtendScript Toolkit Object Model Viewer.
I frequently work on very diverse projects - sometimes it's GWT/Java, sometimes it's ActionScript, sometimes it's PHP/WordPress, sometimes it's C++ or REALbasic, and so on... - and invariably, when I come back to a particular project, I need to spend some time refreshing basic knowledge.
It's like my brain 'switches' programming environment, and when I am deeply immersed in Java, I almost forget how to spell 'EkstentScript'.
The ExtendScript Toolkit Object Model Viewer (you find it under the 'Help' menu) is great for browsing the object model - but when it's been a while, it still feels like I am wading through molasses. One of the reasons for that is that I am a visually-oriented person. A picture is worth a few thousand mouse-clicks to me!
Lately, I've been revisiting BarredText - one of our latest scripted plug-ins, and to do that, I need to get back up to speed on TextFrames, Columns, Characters, Stories, and so on.
I decided I'd put in a little bit more effort, and put everything into a diagram - I've made a 2-page PDF file as a refresher I'll use next time I need to figure out how those buggers relate.
Because this might be useful to other people, I decided to release the PDF file under the 'Attribution-Share Alike' Creative Commons license:
http://www.rorohiko.com/downloads/rorohiko.blogspot.com-extendscript-textframe.pdf
I am not claiming this is error-free - if you find any errors, or can see ways to improve this, please let me know.
And if you like this - let me know too! Soon, I need to revisit tables and cells in ExtendScript - who knows, if I get enough positive feedback I might do another visual representation.
Friday, February 4, 2011
Wednesday, February 2, 2011
Easy Access to System Folders on Mac and Windows
Time for a few tidbits! On my list of 'good intentions' for 2011 is an entry 'write more blog posts'.
My idea is that I want to jot down a quick blog post each time I find myself using a trick or technique that might be useful to others, and that can be explained in a relatively short blog post.
It dawned on me that a lot of tricks I have personally come to find mundane and obvious can be life-changing news to some people. I had forgotten how it was for me, how nothing was obvious, when I started out doing this job long, long time ago.
If you're a hardened, experienced software developer or computer tinkerer - my blog posts are not really for you. You might find the odd gem, but most of the stuff you'll go 'duh - knew that'. But if you're starting out on a new challenge, the wee tricks I'll be describing are things that made my life easier - and I hope they'll make yours easier too.
Ok, to make a living, I am writing software, in various environments, using C++, JavaScript, ExtendScript, REALbasic, PHP, you name it... on Mac, Windows and Linux. As a project grows, invariably I 'll need a spot to put down some 'rubbish' files - temporary files created by my program that are only needed for a little while, and then can get trashed.
Sometimes, while debugging, I want to access those rubbish files with my text editor to inspect their contents - for example, to verify all is well at a certain stage of the program execution.
Mac OS X and Linux (both close relatives of Unix) have a number of spots for storing temporary files - but as on most forms of Unix, you can access that location using the /tmp path. Sometimes /tmp is not a real directory but rather an alias or link to some other place - but that does not matter too much.
If you start a command line session (go to /Applications/Utilities, and start Terminal), you can type
cd /tmp
ls
to see what's in it.
On Windows, you go to the Start button, select the Run... option, and type cmd into the Open field.
Click Ok. That brings up a command line window.
In the command line window, type
cd %TEMP%
dir
to see what's in it.
As it goes, I tend to hop all over the place in my command line sessions - using the cd command to hop from directory to directory.
Occasionally, I find myself in a command line session in a deeply nested directory, and I wish I had a Finder or Explorer window to get a better overview of the directory (aka folder) contents.
That's easy: on Mac, you simply type
open .
And on Windows, you type
explorer .
in the command line (i.e. open<Space><Period><Enter>, or explorer<Space><Period><Enter>), and a Finder or Explorer window will pop up showing the contents of the directory you're in. Then you can start dragging icons of the files you see onto various apps to inspect them. For example, I often use BBEdit, TextWrangler, 0xED on Mac, and UltraEdit or UEStudio on Windows.
If you're on the command line, and you want to inspect a text file in the current directory, that's easy enough too. I am personally well-aquainted with vi, a crusty old Unix text editor, and I use it a lot, but vi is not exactly user-friendly.
No worries - on Mac, if you have TextWrangler installed (which is a free download from BareBones), it should have asked you whether you wanted to install the command line tools. If you're not sure whether you allowed it or not - go to the TextWrangler menu, and select Install Command Line Tools...
From now on, when you're in a command line session in Terminal, you can simply type something like:
edit whateverfilename.log
to inspect the contents of the file whateverfilename.log in TextWrangler, assuming you'd have a file called whateverfilename.log in your current directory.
If you have BBEdit (TextWrangler's big brother) installed, simply substitute bbedit for edit on the command line.
On Windows, it depends on the text editor you have - everyone has Notepad or Wordpad (called write on the command line). If you have UEStudio installed, you can use that too - you could type a command similar to any of the following:
notepad whateverfilename.txt
write anotherfilename.log
uestudio yetanother.out
Now, suppose I wanted to quickly open a Finder window on the /tmp directory without needing to start up the Terminal program. If you go and look on your startup drive, you won't see it - it's there, but the Finder hides system folders like /tmp.
To get there using the Finder, select the Go - Go To Folder... menu item, and type /tmp in the dialog. Click the Go button - and you should get a Finder window on the /tmp folder.
On Windows, to quickly access a hidden folder, you go to the Run... function in the Start menu, and type in the path name. Type %TEMP% to open a window onto the temporary folder. Or type %APPDATA% to get an Explorer window straight onto the current user's hidden application data folder.
On Mac, if you need to be in the /tmp folder a lot (or any other system folder like that - /var/log for example), simply drag the little folder icon of the window for /tmp to the side bar of the Finder window - from now on you can click an icon to have instant Finder access to /tmp
Windows knows the same trick: in the command line window, type cd<Space> and drag the icon from the Explorer address bar into the command line window.
My idea is that I want to jot down a quick blog post each time I find myself using a trick or technique that might be useful to others, and that can be explained in a relatively short blog post.
(The qualifier 'relatively' in the previous sentence is necessary - I tend to have trouble keeping the number of words in a post down to a reasonable number. I'll try to keep it short and to the point!)
It dawned on me that a lot of tricks I have personally come to find mundane and obvious can be life-changing news to some people. I had forgotten how it was for me, how nothing was obvious, when I started out doing this job long, long time ago.
If you're a hardened, experienced software developer or computer tinkerer - my blog posts are not really for you. You might find the odd gem, but most of the stuff you'll go 'duh - knew that'. But if you're starting out on a new challenge, the wee tricks I'll be describing are things that made my life easier - and I hope they'll make yours easier too.
Ok, to make a living, I am writing software, in various environments, using C++, JavaScript, ExtendScript, REALbasic, PHP, you name it... on Mac, Windows and Linux. As a project grows, invariably I 'll need a spot to put down some 'rubbish' files - temporary files created by my program that are only needed for a little while, and then can get trashed.
Sometimes, while debugging, I want to access those rubbish files with my text editor to inspect their contents - for example, to verify all is well at a certain stage of the program execution.
Mac OS X and Linux (both close relatives of Unix) have a number of spots for storing temporary files - but as on most forms of Unix, you can access that location using the /tmp path. Sometimes /tmp is not a real directory but rather an alias or link to some other place - but that does not matter too much.
If you start a command line session (go to /Applications/Utilities, and start Terminal), you can type
cd /tmp
ls
to see what's in it.
On Windows, you go to the Start button, select the Run... option, and type cmd into the Open field.
Click Ok. That brings up a command line window.
In the command line window, type
cd %TEMP%
dir
to see what's in it.
As it goes, I tend to hop all over the place in my command line sessions - using the cd command to hop from directory to directory.
Occasionally, I find myself in a command line session in a deeply nested directory, and I wish I had a Finder or Explorer window to get a better overview of the directory (aka folder) contents.
That's easy: on Mac, you simply type
open .
And on Windows, you type
explorer .
in the command line (i.e. open<Space><Period><Enter>, or explorer<Space><Period><Enter>), and a Finder or Explorer window will pop up showing the contents of the directory you're in. Then you can start dragging icons of the files you see onto various apps to inspect them. For example, I often use BBEdit, TextWrangler, 0xED on Mac, and UltraEdit or UEStudio on Windows.
If you're on the command line, and you want to inspect a text file in the current directory, that's easy enough too. I am personally well-aquainted with vi, a crusty old Unix text editor, and I use it a lot, but vi is not exactly user-friendly.
No worries - on Mac, if you have TextWrangler installed (which is a free download from BareBones), it should have asked you whether you wanted to install the command line tools. If you're not sure whether you allowed it or not - go to the TextWrangler menu, and select Install Command Line Tools...
From now on, when you're in a command line session in Terminal, you can simply type something like:
edit whateverfilename.log
to inspect the contents of the file whateverfilename.log in TextWrangler, assuming you'd have a file called whateverfilename.log in your current directory.
If you have BBEdit (TextWrangler's big brother) installed, simply substitute bbedit for edit on the command line.
On Windows, it depends on the text editor you have - everyone has Notepad or Wordpad (called write on the command line). If you have UEStudio installed, you can use that too - you could type a command similar to any of the following:
notepad whateverfilename.txt
write anotherfilename.log
uestudio yetanother.out
Now, suppose I wanted to quickly open a Finder window on the /tmp directory without needing to start up the Terminal program. If you go and look on your startup drive, you won't see it - it's there, but the Finder hides system folders like /tmp.
To get there using the Finder, select the Go - Go To Folder... menu item, and type /tmp in the dialog. Click the Go button - and you should get a Finder window on the /tmp folder.
On Windows, to quickly access a hidden folder, you go to the Run... function in the Start menu, and type in the path name. Type %TEMP% to open a window onto the temporary folder. Or type %APPDATA% to get an Explorer window straight onto the current user's hidden application data folder.
On Mac, if you need to be in the /tmp folder a lot (or any other system folder like that - /var/log for example), simply drag the little folder icon of the window for /tmp to the side bar of the Finder window - from now on you can click an icon to have instant Finder access to /tmp
Another cool one to have in the sidebar is the Originals or Masters folder inside your Pictures/iPhoto Library folder - you can get at the original files without having to go through the whole right-click, Show Package Contents routine on the iPhoto Library every time. Be careful though: you should only look at, and not touch the contents of those folders.
Windows 7 has a very similar functionality - you can drag folder icons into the Favorites on the sidebar.
Going from Finder or Explorer to Terminal or the Windows command line is also easy. Suppose you have a Finder window open, and you want to get a Terminal window positioned in the same folder.
Go to the Terminal, and type cd<Space>
I hope that was useful! There's more stuff like this I could blog about - let me know whether anyone is interested!
Cheers,
Kris
Wednesday, January 12, 2011
Self-diagnosing code
Been a long time since I wrote a blog post - so here's a short one, about how you can make your ExtendScript code help you diagnose issues, and how to do it without killing the execution speed.
First of all, a fairly long intro about how I make my code self-diagnosing. I'll be skimping on the details - it's all part of my intro, and I'll get to the real point I want to make later.
When writing code, I nearly always routinely add all kinds of logging to the code. For example, every single function I make gets a little 'intro' and a little, er... 'extro' ;-) ?
function blah(var param)
{
... body ...
becomes
function blah(var param)
{
if (kTracing)
{
LogEntry("blah, param = " + param);
}
... body ...
kTracing is a constant that I define somewhere near the top of the script - e.g.
const kTracing = false;
LogEntry and LogExit are two functions I wrote that append their string parameter to a log file.
I won't elaborate on those - they're very simple. In my case they're part of a larger set of 'standard' routines I use in all my scripts - I also have LogError, LogWarning, LogNote...and these all append their information to the same log file, and can be suppressed by modifying a constant kLogLevel. Writing those for yourself is left as an exercise.
Secondly, I religiously test pre-conditions: things that should be true are verified and re-verified. I like using the do-while (false) 'non-loop' construct for bailing out quickly when preconditions are incorrect.
function DoSomethingWithCharacter(c)
{
do // This is not a loop!
{
if (! (c instanceof Character))
{
}
... body of the function ...
}
while (false); // This is not a loop!
}
Not sure whether this is actually any faster than try/catch/throw constructs in ExtendScript, but I do know that in a number of environments like C and C++, try/catch comes with a performance penalty, and might not be available for various complex reasons - whereas I expect do-while(false) to be relatively cheap.
I do use both constructs - I tend to use try/catch/throw more for really catastrophic issues, or as a workaround for InDesign issues (e.g. testing for 'dead' object references) whereas do-while(false) is used for 'controlled failure'.
The code above is self-diagnosing: it spits out error messages into my log file every time something is not quite right, and in my experience, the error messages are more 'pin-point' precise than what you'd get with try/catch; with try/catch I often find myself struggling a bit to find the actual location of the error.
Release versions of my scripts will typically have their log level set to zero (which means calls to LogError and friends amount to almost 'do-nothing', apart from a little overhead). When things go wrong, I modify a few constants (kLogLevel, kTracing) at the top of the script, let it do its thing, and often know what the issue is very soon thereafter.
Writing this kind of code takes a bit of extra effort - but it always pays back for itself the first time I get the first hairy bug to diagnose. It's not always possible to use the ExtendScript Toolkit for a debugging session for various reasons, and having the proper testing and logging code ready-to-go is often a life saver.
Now, that's the intro - now onto the real issue I wanted to discuss.
Adding logging code to all my functions comes at a performance penalty: especially 'deep' routines that are called from within loops are often called thousands or millions of times, and even when kTracing is set to false, this could still incur some overhead.
Now, here's a trick I often use: I use my trusty text editor (BBEdit) to make my logging code disappear and reappear as needed. Here's how it goes: I dress up all my intro and 'extro' code as follows:
...
/*TRACEIN*/if (kTrace)
{
LogEntry("AdjustStory");
}/*TRACEOUT*/
with
/*TRACEIN*-/
and also (even though it is not necessary, but I am obsessive compulsive about this, so I need to do it to keep things 'even')
/*TRACEOUT*/
is replaced with
/-*TRACEOUT*/
As a result, my tracing code now becomes:
...
First of all, a fairly long intro about how I make my code self-diagnosing. I'll be skimping on the details - it's all part of my intro, and I'll get to the real point I want to make later.
When writing code, I nearly always routinely add all kinds of logging to the code. For example, every single function I make gets a little 'intro' and a little, er... 'extro' ;-) ?
function blah(var param)
{
... body ...
return retVal;
}becomes
function blah(var param)
{
if (kTracing)
{
LogEntry("blah, param = " + param);
}
... body ...
if (kTracing)
{
LogExit("blah);
}
return retVal;
}kTracing is a constant that I define somewhere near the top of the script - e.g.
const kTracing = false;
LogEntry and LogExit are two functions I wrote that append their string parameter to a log file.
I won't elaborate on those - they're very simple. In my case they're part of a larger set of 'standard' routines I use in all my scripts - I also have LogError, LogWarning, LogNote...and these all append their information to the same log file, and can be suppressed by modifying a constant kLogLevel. Writing those for yourself is left as an exercise.
Secondly, I religiously test pre-conditions: things that should be true are verified and re-verified. I like using the do-while (false) 'non-loop' construct for bailing out quickly when preconditions are incorrect.
function DoSomethingWithCharacter(c)
{
do // This is not a loop!
{
if (c == null)
{
LogError("DoSomethingWithCharacter: c == null");
break;
}
if (! (c instanceof Character))
{
LogError("DoSomethingWithCharacter: c is not a Character");
break;}
... body of the function ...
}
while (false); // This is not a loop!
}
Not sure whether this is actually any faster than try/catch/throw constructs in ExtendScript, but I do know that in a number of environments like C and C++, try/catch comes with a performance penalty, and might not be available for various complex reasons - whereas I expect do-while(false) to be relatively cheap.
I do use both constructs - I tend to use try/catch/throw more for really catastrophic issues, or as a workaround for InDesign issues (e.g. testing for 'dead' object references) whereas do-while(false) is used for 'controlled failure'.
The code above is self-diagnosing: it spits out error messages into my log file every time something is not quite right, and in my experience, the error messages are more 'pin-point' precise than what you'd get with try/catch; with try/catch I often find myself struggling a bit to find the actual location of the error.
Release versions of my scripts will typically have their log level set to zero (which means calls to LogError and friends amount to almost 'do-nothing', apart from a little overhead). When things go wrong, I modify a few constants (kLogLevel, kTracing) at the top of the script, let it do its thing, and often know what the issue is very soon thereafter.
Writing this kind of code takes a bit of extra effort - but it always pays back for itself the first time I get the first hairy bug to diagnose. It's not always possible to use the ExtendScript Toolkit for a debugging session for various reasons, and having the proper testing and logging code ready-to-go is often a life saver.
Now, that's the intro - now onto the real issue I wanted to discuss.
Adding logging code to all my functions comes at a performance penalty: especially 'deep' routines that are called from within loops are often called thousands or millions of times, and even when kTracing is set to false, this could still incur some overhead.
Now, here's a trick I often use: I use my trusty text editor (BBEdit) to make my logging code disappear and reappear as needed. Here's how it goes: I dress up all my intro and 'extro' code as follows:
...
/*TRACEIN*/if (kTrace)
{
LogEntry("AdjustStory");
}/*TRACEOUT*/
...
When the code is ready for a production environment, I do a global search-and-replace and replace
/*TRACEIN*/with
/*TRACEIN*-/
and also (even though it is not necessary, but I am obsessive compulsive about this, so I need to do it to keep things 'even')
/*TRACEOUT*/
is replaced with
/-*TRACEOUT*/
As a result, my tracing code now becomes:
...
/*TRACEIN*-/if (kTrace)
{
LogEntry("AdjustStory");
}/-*TRACEOUT*/
...
If you look closely, you'll see the whole construct is now a 3-line comment, which will almost certainly be less costly in performance. I can only guess how the ExtendScript engine works, but I suspect that the only cost will be a tiny bit of time when the script is parsed, and there would be no additional cost during repeated execution of the function.
Furthermore, my scripts often are packaged up as .spln files (using Active Page Item Developer), and this automatically strips out all comments when creating a release version of an .spln - so when using this for .spln development, the entry/exit logging code is guaranteed to be completely gone.
When an issue arises, I simply perform the reverse search-and-replace, and re-enable my disabled logging code.
There's lot of additional things you can do with logging - I've only scratched the surface here. For example, sometimes I use an XML format for output of the logging - and the extra effort to do that is rewarded by the fact that I can use an XML editor or XML browser to selectively hide and show whole sections of the log. Anyway, depending on feedback, I might do another post some time later on a few more of these techniques.
Sunday, June 6, 2010
Don't Be a Tech Support Nightmare
Synopsis: even if you're under stress, try to communicate clearly with the people in tech support. There's a little checklist at the end of this post.
It might come as a surprise, but in small companies like Rorohiko, tech support is being run by real, live people. We don't have a complex automated response system - if you e-mail support@rorohiko.com, you'll be answered by a real person. We go to great efforts to run a tidy, responsive tech support department. We provide world-class support on our software - whether it is free or not. We respond quickly to e-mails, most of the time within hours.
Yet we still run into the occasional tech support nightmare.
The problems we're facing are manyfold.
1) Not Enough Info
First of all, people often don't give tech support people any information at all, or way too little. You'd be surprised how many times we get an email that simply states:
"Dear support,
It does not work. Please fix ASAP!
Bye,
John"
This is sometimes prefaced with some upset diatribe about things being urgent.
We then need to guess what 'it' is? More than once the 'it' that did not work turned out to be a software from a different company all together.
(So - no, we don't do electronic PCB design. Nor knitting patterns. And no, we're not Adobe. We make task tools to help do things faster with InDesign - plug-ins, extensions, little applications. We don't make InDesign).
As we're servicing both people on Macintosh and Windows, we also need to figure out whether this person is using a Mac or Windows, and what the version is of their OS - XP, Vista, OS X 10.5, OS X 10.6? Then we also often need to know what version of InDesign they are using.
We sometimes use little tricks like looking at the raw e-mail headers of their e-mail - that might give us a clue whether they're Mac or Windows users, and sometimes even what version of the OS they're using. So if their hidden e-mail header says their e-mail program is Outlook, that's a give-away that they're on Windows.
2) We Cannot Reach The Person In Need
Our e-mails get thrashed by their spam-killer.
Or their e-mail server rejects our e-mails because it deems them suspicious - so we get our e-mails back after a few days with 'Undelivered e-mail returned to sender'.
Or our e-mails don't get through because their e-mail inbox is full.
So the scenario is like this: we get a question, and we reply, typically within a few hours. Our reply does not reach its destination.
We get an upset follow-up. We try to use a different 'sending' e-mail address, most of the time to no avail. We get an even more upset follow up,... and so on.
Sometimes people also post messages on forums saying things like 'Rorohiko does not answer e-mails'.
Luckily, most people have an e-mail signature, and such e-mail signature is a really Good Thing as it often contains a phone number. If we notice e-mails being bounced and we have a phone number, we give them a call - problem fixed.
But all too often there is no phone number - all we have is a first name and some email address @gmail.com or @hotmail.com. What's a tech support person to do?
3) Not Enough Answers
The third problem is that people often are unable to answer the questions we ask - they're often under stress, and have trouble concentrating on what we ask them. A dialog could go like this:
>>>
<<<
<<<
>>>
(ok - here we can kind of guess the issue might be with our TextExporter - that's the tool we most commonly see being used together with InDesign and MS Word).
4) Don't Contact support@rorohiko.com - Post It On a Forum Instead
This is one of the biggest issue we're facing. Instead of asking us for help, some people simply assume they are on their own, and look for help with our software on public forums.
That's OK - the people on those forums are often very knowledgeable, and very helpful, and you might get a solution, or they will point you to support@rorohiko.com.
The problem is that we're kept out of the loop - i.e. if there's a problem with any of our software, we'd love to hear about it.
So, our plea: if you have any issues with our software, let us know!
5) Web Sites Do Go Down
We are using an ISP located in the USA, and we're pretty happy with them (http://www.arvixe.com if you need to know).
But every so often, just like everyone else's, our web site goes down for 10, 20, 50... minutes. It might be DNS failure, a hardware replacement,... Sometimes there's some other internet issue.
If you try to reach http://www.rorohiko.com and you cannot reach the web site here's what you should do:
1) E-mail support@rorohiko.com to let us know that our web site is down - we're not continuously monitoring it, so we're always happy if someone helps us out by letting us know.
2) Sit tight, and try again in a few hours.
Here's what you should not do:
1) Assume that because our web site is down, something must be horribly wrong
2) Put posts on public forums asking whether Rorohiko has gone out of business because their web site is down
6) We're In a Different Time Zone
Rorohiko is based in New Zealand. That means we're in a different time zone - so you might not always get an immediate response to your e-mail. We're almost a day ahead of the USA - so what is Friday in the USA is already Saturday here in New Zealand. If you e-mail us on Friday, we might already be out fishin'.
Most of the time we do keep our support department active over the weekend, but occasionally, e-mails won't be answered until after the weekend.
7) Be Impolite And Demanding On Forums
This is not an issue that affects us in tech support, but we do see it happen a lot, and I wanted to address it here, because it is also a communication issue.
Various forums like http://forums.adobe.com are run by volunteers - people willing to sacrifice their own time and knowledge for the greater good.
All too often, someone under stress busts in on these forums, and starts demanding a solution for a problem, preferably in ALL CAPS, and they NEED IT NOW.
Please, don't do that - keep in mind that software forums are like tech support run by volunteers. If a forum post does not get answered: that's how it goes. You cannot force volunteers to help you fix your problem.
Being polite helps. Being complete and concise helps too. Building goodwill by helping others in need helps too - so if you can help someone else, do it. By doing that, you increase your chances of being helped when the time comes you need it.
But don't expect help if you go bustin' in yelling you need help NOW.
Conclusion
So - if you are ever in the position of needing tech support - please think of the recipient at the other end, and help them help you.
Provide ample information from the first e-mail or post you send:
- Who are you? Make sure to leave enough info so you can be contacted. Provide an alternate e-mail address. Provide a phone number.
- What is it about? Make sure you explain what the name of the software or tool is you're having trouble with.
- What is the problem? Describe in detail what steps you are taking and where it goes wrong (e.g. something like "I then try to select the File - Open... menu but it is greyed out")
- Which platform are you on: Mac/Windows? What version of the OS? XP, Server 2008, Vista, Vista 64, Win7, Win7 64, OS X 10.4.x, OS X 10.5.x,...
- What version of the creative suite are you using: CS, CS2, CS3, CS4, CS5?
- Do you know how to create a system profile on Mac? (Go to the 'Apple - About this Mac' menu then click 'More Info...' and use 'File - Save As...' to save a system profile. Attach it to your e-mail).
- What version of InDesign are you using? CS4 has a whole range: 6.0, 6.0.1,... 6.0.5?
- Can you make one or more screenshots of the problem? If so, please do
- Can you provide a sample document? If you can, please do (but don't send a 1GB sample - try to make it as small as possible)
- Did something crash? If so, can you get the crash logs and e-mail them? If you don't know what those are, can you find someone to help you with that?
Finally, answer all questions you get in return to the best of your capacity.
In this blog post, I want to share some issues people in tech support are facing, and raise some awareness of the difficulties anyone in tech support has to contend with.
It all comes down to communication, or a breakdown thereof.
I am sure a lot of other small software companies are facing the same issues - so please, takes this plea to heart next time you're dealing with software created by a small company.
Yet we still run into the occasional tech support nightmare.
The problems we're facing are manyfold.
1) Not Enough Info
First of all, people often don't give tech support people any information at all, or way too little. You'd be surprised how many times we get an email that simply states:
"Dear support,
It does not work. Please fix ASAP!
Bye,
John"
This is sometimes prefaced with some upset diatribe about things being urgent.
We then need to guess what 'it' is? More than once the 'it' that did not work turned out to be a software from a different company all together.
(So - no, we don't do electronic PCB design. Nor knitting patterns. And no, we're not Adobe. We make task tools to help do things faster with InDesign - plug-ins, extensions, little applications. We don't make InDesign).
As we're servicing both people on Macintosh and Windows, we also need to figure out whether this person is using a Mac or Windows, and what the version is of their OS - XP, Vista, OS X 10.5, OS X 10.6? Then we also often need to know what version of InDesign they are using.
We sometimes use little tricks like looking at the raw e-mail headers of their e-mail - that might give us a clue whether they're Mac or Windows users, and sometimes even what version of the OS they're using. So if their hidden e-mail header says their e-mail program is Outlook, that's a give-away that they're on Windows.
2) We Cannot Reach The Person In Need
Our e-mails get thrashed by their spam-killer.
Or their e-mail server rejects our e-mails because it deems them suspicious - so we get our e-mails back after a few days with 'Undelivered e-mail returned to sender'.
Or our e-mails don't get through because their e-mail inbox is full.
So the scenario is like this: we get a question, and we reply, typically within a few hours. Our reply does not reach its destination.
We get an upset follow-up. We try to use a different 'sending' e-mail address, most of the time to no avail. We get an even more upset follow up,... and so on.
Sometimes people also post messages on forums saying things like 'Rorohiko does not answer e-mails'.
Luckily, most people have an e-mail signature, and such e-mail signature is a really Good Thing as it often contains a phone number. If we notice e-mails being bounced and we have a phone number, we give them a call - problem fixed.
But all too often there is no phone number - all we have is a first name and some email address @gmail.com or @hotmail.com. What's a tech support person to do?
3) Not Enough Answers
The third problem is that people often are unable to answer the questions we ask - they're often under stress, and have trouble concentrating on what we ask them. A dialog could go like this:
>>>
It does not work. Please fix ASAP!
<<<
Hi,... So sorry to hear that.
Could you let us know the name of the software you're having trouble with?
Also, we need to know whether you are on a Mac or on Windows.
Furthermore, let us know what version of the OS you're using: is it XP, Vista, Windows 7? Or OS X 10.4, 10.5 or 10.6?
And if InDesign is involved, please give us the version number - CS, CS2,... CS5?
Thanks so much!
Rorohiko Support
Could you let us know the name of the software you're having trouble with?
Also, we need to know whether you are on a Mac or on Windows.
Furthermore, let us know what version of the OS you're using: is it XP, Vista, Windows 7? Or OS X 10.4, 10.5 or 10.6?
And if InDesign is involved, please give us the version number - CS, CS2,... CS5?
Thanks so much!
Rorohiko Support
>>>
I am on CS4. I need to get this out by tomorrow. Please FIX ASAP! IT IS URGENT
<<<
Thanks so much for that information! That helps a bit - but we need more. What is the name of the software you're having trouble with? We have many products available, so it could be any one of them.
Rorohiko Support
Rorohiko Support
>>>
The product is called Adobe InDesign. And MS Word. HELP ME!
(ok - here we can kind of guess the issue might be with our TextExporter - that's the tool we most commonly see being used together with InDesign and MS Word).
and the e-mail ping-pong drags on...
4) Don't Contact support@rorohiko.com - Post It On a Forum Instead
This is one of the biggest issue we're facing. Instead of asking us for help, some people simply assume they are on their own, and look for help with our software on public forums.
That's OK - the people on those forums are often very knowledgeable, and very helpful, and you might get a solution, or they will point you to support@rorohiko.com.
The problem is that we're kept out of the loop - i.e. if there's a problem with any of our software, we'd love to hear about it.
So, our plea: if you have any issues with our software, let us know!
5) Web Sites Do Go Down
We are using an ISP located in the USA, and we're pretty happy with them (http://www.arvixe.com if you need to know).
But every so often, just like everyone else's, our web site goes down for 10, 20, 50... minutes. It might be DNS failure, a hardware replacement,... Sometimes there's some other internet issue.
If you try to reach http://www.rorohiko.com and you cannot reach the web site here's what you should do:
1) E-mail support@rorohiko.com to let us know that our web site is down - we're not continuously monitoring it, so we're always happy if someone helps us out by letting us know.
2) Sit tight, and try again in a few hours.
Here's what you should not do:
1) Assume that because our web site is down, something must be horribly wrong
2) Put posts on public forums asking whether Rorohiko has gone out of business because their web site is down
6) We're In a Different Time Zone
Rorohiko is based in New Zealand. That means we're in a different time zone - so you might not always get an immediate response to your e-mail. We're almost a day ahead of the USA - so what is Friday in the USA is already Saturday here in New Zealand. If you e-mail us on Friday, we might already be out fishin'.
Most of the time we do keep our support department active over the weekend, but occasionally, e-mails won't be answered until after the weekend.
7) Be Impolite And Demanding On Forums
This is not an issue that affects us in tech support, but we do see it happen a lot, and I wanted to address it here, because it is also a communication issue.
Various forums like http://forums.adobe.com are run by volunteers - people willing to sacrifice their own time and knowledge for the greater good.
All too often, someone under stress busts in on these forums, and starts demanding a solution for a problem, preferably in ALL CAPS, and they NEED IT NOW.
Please, don't do that - keep in mind that software forums are like tech support run by volunteers. If a forum post does not get answered: that's how it goes. You cannot force volunteers to help you fix your problem.
Being polite helps. Being complete and concise helps too. Building goodwill by helping others in need helps too - so if you can help someone else, do it. By doing that, you increase your chances of being helped when the time comes you need it.
But don't expect help if you go bustin' in yelling you need help NOW.
Conclusion
So - if you are ever in the position of needing tech support - please think of the recipient at the other end, and help them help you.
Provide ample information from the first e-mail or post you send:
- Who are you? Make sure to leave enough info so you can be contacted. Provide an alternate e-mail address. Provide a phone number.
- What is it about? Make sure you explain what the name of the software or tool is you're having trouble with.
- What is the problem? Describe in detail what steps you are taking and where it goes wrong (e.g. something like "I then try to select the File - Open... menu but it is greyed out")
- Which platform are you on: Mac/Windows? What version of the OS? XP, Server 2008, Vista, Vista 64, Win7, Win7 64, OS X 10.4.x, OS X 10.5.x,...
- What version of the creative suite are you using: CS, CS2, CS3, CS4, CS5?
- Do you know how to create a system profile on Mac? (Go to the 'Apple - About this Mac' menu then click 'More Info...' and use 'File - Save As...' to save a system profile. Attach it to your e-mail).
- What version of InDesign are you using? CS4 has a whole range: 6.0, 6.0.1,... 6.0.5?
- Can you make one or more screenshots of the problem? If so, please do
- Can you provide a sample document? If you can, please do (but don't send a 1GB sample - try to make it as small as possible)
- Did something crash? If so, can you get the crash logs and e-mail them? If you don't know what those are, can you find someone to help you with that?
Finally, answer all questions you get in return to the best of your capacity.
Just sayin'
Cheers,
Kris
Sunday, December 27, 2009
Kill The Caps Lock!
Here's a little tidbit that has made my life a little bit easier: kill the Caps Lock on your Mac.
I don't think I've ever used the Caps Lock key - all it's ever done for me is cause pain and grief and wrong passwords or inadvertent 'shouting' in e-mails. It's a fossil from days gone by.
Go into System Preferences, select the 'Keyboard and Mouse' or 'Keyboard' panel, click 'Modified keys...'
and set the Caps Lock key to 'No Action'.
Takes all of 10 seconds!
I don't know about you, but I love it.
Cheers,
Kris
I don't think I've ever used the Caps Lock key - all it's ever done for me is cause pain and grief and wrong passwords or inadvertent 'shouting' in e-mails. It's a fossil from days gone by.
Go into System Preferences, select the 'Keyboard and Mouse' or 'Keyboard' panel, click 'Modified keys...'
and set the Caps Lock key to 'No Action'.
Takes all of 10 seconds!
Cheers,
Kris
Thursday, November 26, 2009
BBEdit and ExtendScript
Quick tidbit for my fellow ExtendScripters. I am using BBEdit as my main text editor on Mac OS X, and I've set it so .jsx files are seen as JavaScript files. That adds lot of nice features that are also handy when working on an ExtendScript.
But when I am working on an ExtendScript, there is this little annoying thing: each time I started typing
try
followed by a return, BBEdit's auto-completion would kick in and convert it to something like
Try.these(
function() { ... },
foo.bar.bind(),
this.bat.bind()
)
Gaah! I didn't want that!
One of these minor annoyances - not enough to spend time on, got code to write, right?
But eventually, I got annoyed enough so I did the Right Thing and looked into it.
It's simple enough to clear up:
In the Finder, go to your home folder
Go into Library, then Application Support, then BBEdit, then Clippings, then JavaScript.js, then Prototype, then get rid of the file called Try.these
Oh bliss! It's like removing a pesky pebble from your shoe!
Some time later, I'll look into creating a proper 'try - catch' autocompletion that matches my ExtendScript behavior, but for now, just getting rid of this is just great!
But when I am working on an ExtendScript, there is this little annoying thing: each time I started typing
try
followed by a return, BBEdit's auto-completion would kick in and convert it to something like
Try.these(
function() { ... },
foo.bar.bind(),
this.bat.bind()
)
Gaah! I didn't want that!
One of these minor annoyances - not enough to spend time on, got code to write, right?
But eventually, I got annoyed enough so I did the Right Thing and looked into it.
It's simple enough to clear up:
In the Finder, go to your home folder
Go into Library, then Application Support, then BBEdit, then Clippings, then JavaScript.js, then Prototype, then get rid of the file called Try.these
Oh bliss! It's like removing a pesky pebble from your shoe!
Some time later, I'll look into creating a proper 'try - catch' autocompletion that matches my ExtendScript behavior, but for now, just getting rid of this is just great!
Friday, October 23, 2009
InDesign Scripters and Plug-In Developers: How To Avoid Confusing File Duplications
In short: how to avoid copying or shuffling scripts and plug-ins during development on Mac or Windows.
When it comes to scripts or plug-ins, Mac alias files can be used as if they are 'the real thing' - InDesign will treat an alias file as if it is the script or plug-in it is referring to. I'll explain how you can use that feature to your advantage.
Sadly enough, a Windows shortcut file is not treated with the same respect by InDesign - a Windows shortcut file is simply ignored, so shortcuts are out.
Luckily, Windows has a 'hard-linking' feature that can be used in the same way as Mac alias files - I'll explain that too.
The basic idea is to avoid 'scattering' copies of your script or plug-in around your hard disk. As soon as you start copying stuff around, it becomes easy to lose track of which is which, and in the heat of the moment, you might get older and newer versions mixed up.
A typical scenario would be: you're creating a script that needs to work both on InDesign CS3 and InDesign CS4. You're testing and debugging - and each time you want to swap between CS3 and CS4, you need to copy the script in progress from one Scripts folder to the other.
And then the phone rings, and you're caught in mid-swap. After the phone call, you forgot: did you complete the copy or not? So, where is the most recent version - in the CS3 folder or in the CS4 folder? Frustrating, isn't it?
To avoid doing 'the shuffle', you can instead store a single 'master copy' of your plug-in or script somewhere on your hard disk.
If you are using a source code control system like SVN or CVS, the master copy would probably reside somewhere in a folder structure managed with the source code control system.
Then, instead of copying the script or plug-in to it's 'active location' (e.g. one of the InDesign plug-ins folder, or one of the InDesign scripts folders), you instead create a 'stand-in' which always refers back to the master copy of the file.
On Mac, you can use an alias file for that - pretty easy. Create an alias of the script or plug-in and plunk the alias into the proper InDesign subfolder - and everything will work as if the 'real thing' was there.
On Windows, you might be tempted to try shortcut files - but that does not work. Instead, you need to use a hard link, which you can create from a command-line window with the following command:
fsutil hardlink create [destination] [original]
where [destination] is the path of the hard link to be created and [original] is the path of the original file. Depending on your setup and Windows OS version, you might need to launch the command-line window as user 'Administrator', so you have enough privileges.
You can use this command to create hard links to folders as well as files - but I recommend you only use it for hard links to files.
Also keep in mind that this command only works on NTFS volumes (so FAT volumes are out), and both original and destination need to be on the same volume - but in most cases that's all you need.
Hard links are a low-level NTFS feature, and hard links to folders are not well supported in Explorer - and as a result, they're very dangerous things - they don't behave like Windows shortcuts, and that is where the danger lies.
Suppose you had created a hard link from a folder, and then you attempt to delete the hard link later on. Doing that in Explorer would actually also delete all the items that reside in the original folder - not what you'd expect. Explorer treats the hard link as the real thing, and when you delete a folder, it simple-mindedly will empty the folder first - blissfully unaware that the folder is still being used via the original directory entry.
Once a hard link to a folder is created, it's not easy to get rid of without also losing the contents of the folder.
In short: avoid issues - only create hard links to files on Windows; that's much safer.
There's another caveat with regards to hard links on Windows. If you use a hard link to a script file, you must make sure that the text editor program you use does not create backup files because that tends to mess up the hard link - typically, the text editor will simply rename the original file 'test.jsx' to 'test.jsx.bak' or so - taking the hard link along, so it now refers to the .bak file instead of the modified .jsx file.
Turn the backup feature off, and all will be well. I've tried it with Notepad and ExtendScript toolkit, and things seem to work well: if I edit the script via its hard link, the original script is updated as well. I also use UEStudio as a text editor - and at first I ran into problems because this editor makes .bak files by default. Once I switched that off, things worked well.
With regards to maintaining hard links to plug-ins generated from Visual Studio: make sure to use Build, not Rebuild - Rebuild will destroy the original and break the link.
So, that's it for now - hope this makes your life a bit easier!
When it comes to scripts or plug-ins, Mac alias files can be used as if they are 'the real thing' - InDesign will treat an alias file as if it is the script or plug-in it is referring to. I'll explain how you can use that feature to your advantage.
Sadly enough, a Windows shortcut file is not treated with the same respect by InDesign - a Windows shortcut file is simply ignored, so shortcuts are out.
Luckily, Windows has a 'hard-linking' feature that can be used in the same way as Mac alias files - I'll explain that too.
The basic idea is to avoid 'scattering' copies of your script or plug-in around your hard disk. As soon as you start copying stuff around, it becomes easy to lose track of which is which, and in the heat of the moment, you might get older and newer versions mixed up.
A typical scenario would be: you're creating a script that needs to work both on InDesign CS3 and InDesign CS4. You're testing and debugging - and each time you want to swap between CS3 and CS4, you need to copy the script in progress from one Scripts folder to the other.
And then the phone rings, and you're caught in mid-swap. After the phone call, you forgot: did you complete the copy or not? So, where is the most recent version - in the CS3 folder or in the CS4 folder? Frustrating, isn't it?
To avoid doing 'the shuffle', you can instead store a single 'master copy' of your plug-in or script somewhere on your hard disk.
If you are using a source code control system like SVN or CVS, the master copy would probably reside somewhere in a folder structure managed with the source code control system.
Then, instead of copying the script or plug-in to it's 'active location' (e.g. one of the InDesign plug-ins folder, or one of the InDesign scripts folders), you instead create a 'stand-in' which always refers back to the master copy of the file.
On Mac, you can use an alias file for that - pretty easy. Create an alias of the script or plug-in and plunk the alias into the proper InDesign subfolder - and everything will work as if the 'real thing' was there.
On Windows, you might be tempted to try shortcut files - but that does not work. Instead, you need to use a hard link, which you can create from a command-line window with the following command:
fsutil hardlink create
where [destination] is the path of the hard link to be created and [original] is the path of the original file. Depending on your setup and Windows OS version, you might need to launch the command-line window as user 'Administrator', so you have enough privileges.
You can use this command to create hard links to folders as well as files - but I recommend you only use it for hard links to files.
Also keep in mind that this command only works on NTFS volumes (so FAT volumes are out), and both original and destination need to be on the same volume - but in most cases that's all you need.
Hard links are a low-level NTFS feature, and hard links to folders are not well supported in Explorer - and as a result, they're very dangerous things - they don't behave like Windows shortcuts, and that is where the danger lies.
Suppose you had created a hard link from a folder, and then you attempt to delete the hard link later on. Doing that in Explorer would actually also delete all the items that reside in the original folder - not what you'd expect. Explorer treats the hard link as the real thing, and when you delete a folder, it simple-mindedly will empty the folder first - blissfully unaware that the folder is still being used via the original directory entry.
Once a hard link to a folder is created, it's not easy to get rid of without also losing the contents of the folder.
In short: avoid issues - only create hard links to files on Windows; that's much safer.
There's another caveat with regards to hard links on Windows. If you use a hard link to a script file, you must make sure that the text editor program you use does not create backup files because that tends to mess up the hard link - typically, the text editor will simply rename the original file 'test.jsx' to 'test.jsx.bak' or so - taking the hard link along, so it now refers to the .bak file instead of the modified .jsx file.
Turn the backup feature off, and all will be well. I've tried it with Notepad and ExtendScript toolkit, and things seem to work well: if I edit the script via its hard link, the original script is updated as well. I also use UEStudio as a text editor - and at first I ran into problems because this editor makes .bak files by default. Once I switched that off, things worked well.
With regards to maintaining hard links to plug-ins generated from Visual Studio: make sure to use Build, not Rebuild - Rebuild will destroy the original and break the link.
So, that's it for now - hope this makes your life a bit easier!
Subscribe to:
Posts (Atom)
