How to write US request
The people in user support team are not omniscient. By keeping to several dos and dont's you can help them to localize your problem faster.
- Apart from your civil name, always include your username (login).
- There may be more people with identical name/surname.
- The username is unique.
Describe the environment you work from
- Specify job full ID, directory/frontend/node you work from, which modules were loaded.
- Some applications can be run by several ways - e.g. loaded as a module or run as a Singularity image or as OnDemand alication.
- Always specify which way you used to run the software.
Whenever possible, use copy-paste style
- Don't hesitate to copy-paste error messages into your request.
- The same applies for describing your own actions - just paste the string of commands you typed.
- If the error message is too long, include it in a separate file.
- Writing something like "program XY has problem with library YY" does not help us much.
- Where is the library? What problem exactly? We need to see details.
Write a descriptive subject
- Describe in the subject what you observe at current point.
- Be specific.
- Use formulations like "Ansys fails right after start" rather than "Problem with Ansys", or "I need help with installing XY by Conda" rather than "Question about installation".
Tell us which parts of documentation you searched through
- Often our first action is to navigate user to a certain section of documentation.
- If you have already read through the documentation and it did not help solve your issue, tell us about this!
- Plus, it is the good feedback for us that the documentation is possibly not quite clear and/or complete.
Tell us also what worked
- If you have a slightly alternate example that did work, tell us about it.
- E.g. if the job runs OK on some cluster, but fails on another; if it runs on one CPU, but fails on two or more... you get it.
If possible, prepare a smallest possible example how to reproduce the issue
- If you have already investigated the problem on your own, you might have some reduced example how to reproduce the failure.
- Attach this example or a link to a directory where we can find it.
Don't send your request to staff members directly
- Always send requests to firstname.lastname@example.org instead of staff members directly.
- The emails sent to email@example.com are visible to all members of user support and will be picked up by the correct specialist.
- Many staff members work only part time at US desk and may have day-offs.
- And we are sometimes sick or on holidays, too.
New problem, new request
- For new issues unrelated to your previous one, write a new request.
- Do not respond to your latest email from user support - this will reopen your old ticket.
Tell us also about what you finally need to achieve
If you struggle with Y but really what you are after is X, please also tell us about X.
Aka avoid "The XY problem"
What is XY problem?
Typical setup is as follows:
- User wants to do X.
- User doesn't know how to do X, but thinks they can do it if they can just manage to do Y.
- User doesn't know how to do Y either.
- User asks for help with Y.
- Others try to help user with Y, but are confused because Y seems like a strange problem to want to solve.
- After much interaction, it finally becomes clear that the user really wants help with X, and that Y wasn't even a suitable solution for X.