Important: This article is written by Keith Rice from CADSharp LLC.
In a hurry? Skip right to the section called Guidelines for the meat of this article.
Introduction
Over one year ago we introduced tech support through Slack, where you can ask your SOLIDWORKS API and PDM API questions to our team and get high-quality answers within hours or even minutes. Our members have absolutely loved it for its speed and simplicity. But whether you’re posting in our Slack, the SOLIDWORKS API forum, or StackOverflow for a general programming question, these four little words carry so much truth:
“Help us help you.”
Indeed, one of the most frustrating parts of using any technical support resource, whether you’re helping others or simply doing research, is wading through a long thread in which the experts are trying to extract all of the necessary information from the asker so they can actually offer help. Technical help sites like StackOverflow deal with this problem by using a Q&A format instead of a forum / thread format, but they still constantly delete low-quality questions in which the asker didn’t “help us help you”.
All of this to say: asking a well-written programming-related question takes a lot of effort and is not intuitive to many askers. In this post I hope I can give you some clear-cut rules for guaranteeing that your question conveys all of the information necessary for an expert to help you get the answer you need as quickly as possible. By doing so you will protect your time and theirs.
Guidelines
1. Keep it short, simple, and to the point
a. Your first sentence should state your question or summarize your problem.
b. Questions with unnecessary details and background explanations are harder to answer.
c. Use a bullet or number list to convey details. They’re easier to read than paragraphs.
d. Break complicated problems down into smaller problems and post about each problem separately.
2. Share the minimum amount of info necessary to completely convey the problem
a. Please post any relevant code. If you do post code:
i. Only include code that is necessary to repeat the problem.
ii. Your code should compile. Do not post a code snippet that others are forced to complete in order to test.
b. If you’re getting an error message, share that error message and what line it occurs on.
c. If your problem occurs only under a certain situation in SolidWorks (e.g., when a certain model is oepn):
i. State specifically what that situation is.
ii. Include the simplest possible model that includes that situation, if necessary.
3. Proofread your question
a. At CADSharp, we speak over fifteen languages between all of our technical support representatives. If you would prefer to receive help in another language, just ask. But no matter what language you use, be sure to proofread your question so its as clear as possible.
Example
Let me share an example of poor a question / request:
===============
My boss has asked me to write some macros that prepare our models for-check in. The macro needs to check each part and add a Material property if it doesn’t exist. Should also put the Description property in each configuration and the delete the Author property. Works on my test models but stopped working on my production models. Here is the code:
swModel.DeleteCustomInfo2(“Default”, “test”)===============
Unfortunately, this help request is so lacking that I would be wasting my time even trying to help this person. The main reason is that I would be guessing as to what their problem is and might potentially solve a problem they don’t have. Specifically, this is how this question should be improved:
- Clarify whether the macro is run in a part, assembly, or both.
- Clarify whether custom properties are supposed to be added to assembly components or only part components.
- Clarify whether the Description property is supposed to be moved or copied.
- Clarify whether the Author property is deleted from the document-level custom properties, the configuration-level custom properties, or both.
- Use bullet or number lists to differentiate the different problems.
- Give an explanation of what “stopped working” means. Does it mean the macro runs successfully but produces incorrect results or does it mean that an error occurs (and what is the error message)? Does it refer to some or all of the tasks?
- Include the full source code.
- Include a sample model.
Obviously this is an exaggerated example, but I have read some help requests before like this. Keep in mind: technical support cannot read your mind. Instead of assuming they are familiar with your workflow (simply because it makes so much sense to you!), put yourself in their shoes and ask, “What would they need need to know to solve my issue?”
The XY Problem
The above guidelines assume that the asker knows what their problem is. Sometimes, this isn’t the case, and it can waste a lot of time for both the asker and the support technician. The situation I’m speaking of is known as the XY Problem. It occurs when someone asks for help with their attempted solution rather than their actual problem. A good example in the SOLIDWORKS API world would be someone asking for help on getting a point on a face so they can select it with IModelDocExtenion.SelectByID2, when in reality they should have simply asked for help on how the best way to select a particular face, because the aforementioned API call is not appropriate for selecting faces.
Basically, the XY Problem is a technical term to describe askers who are ignorantly pursuing the wrong solution. While its great to encourage people to step back and think, “What problem am I actually trying to solve?”, the XY problem itself is problematic for two reasons:
- Sometimes its just as much a waste of time to wade through lots of background information on the problem only to discover that the user was pursuing the correct solution.
- The simple fact is that much of the time the asker will not know enough about the subject at hand to know whether they are asking the wrong the question. In that case, it is the support technician’s responsibility to ask the questions necessary to uncover the actual problem.
I get the impression that this term was coined by support technicians or forum participants who easily get annoyed helping askers — which is frequently the case on sites like StackOverflow, some of whose users are known for their alarming rudeness and presumptuousness.
When you use CADSharp’s technical support, you can be assured that even if you’re asking the wrong question, you will always be treated with kindness and patience, because its our pleasure to help you reach your SOLIDWORKS API and PDM API automation goals.
Helping you help us help you,
Keith