About
Writing good topics to get help more effectively and quickly
Who is this for?
Anyone creating a topic to get help on a current technical issue
How to write a question topic
You need to ensure people understand what your question is about very quickly so they can judge rapidly if they might be able to help and should keep reading or not. You will also get help faster and more efficiently if your first post contains all the required information.
It is possible to use the guidelines from Stackoverflow to help you write your question. Hereafter is a condensed version of these guidelines specific to the ACCESS-Hive forum.
Avoid duplicates
Duplicated questions make it hard for other users to find the solution to a similar problem. Search the forum first to see if the question has already been asked. If you find similar topics but you think your question is different, make sure you specify why your question is different when you write it. Feel free to link to other similar questions.
Introduce the topic
The title
Other people will decide whether to read your post or not depending on its title. Short titles aren’t necessarily better. Make sure your title reflects what your specific question is about:
- include the language, library, and software specifics as necessary
- if the question is about a specific error message, include the message in the title
The category
People can watch specific categories to be notified of any new activity. The choice of category is important and may ensure that people with the right knowledge will see your question.
The tags
Tags are important as they allow others to find your topic. It is a good idea to add tags around:
- programming language used
- model used and version
See the tags docs topic for more detail about tagging.
Your post
Finally, your post should start with a description of what you are trying to achieve and what you expect the outcome should be. This can be pretty short.
Bad example: My code is crashing. See my code here.
Better: I want to interpolate the 3D air temperature using bilinear interpolation from the ACCESS-CM2 N96 grid onto a regular 1x1° grid. I am using xESMF but it is returning an error.
Details to include in your post
DO NOT attach any picture with code, command lines or error messages to your post. The best is for you to share these through code blocks or to follow these recommendations for Jupyter Notebooks. You can again refer to Stackoverflow for an extensive list of reasons (some of them pertaining to promoting accessibility for all) behind this injunction.
Once you have introduced what you are trying to do, make sure you include enough details in your post so people understand all the parameters of what you are doing:
- the environment:
- what machine are you working on?
- at NCI, are you working on ARE, on a Gadi login node, in a job submitted to the queue, etc.
- what software do you have loaded/installed? Include information on the versions you are using if possible. For example, on Gadi, include the version of the modules you have loaded.
- what machine are you working on?
- what you have executed:
- for a question on a problem with command line tools, the best is to copy and paste the exact suite of commands in a code block on the forum.
- for a question on a code you are writing, you will want to share a code others can use. This means you may have to prepare a minimal reproducible example. For example, you may have to change the input data to some randomly generated arrays of the same shape and dimensions as not everyone might have access to your input data. You also want to limit the code to the part that is strictly necessary to reproduce the behaviour.
- details of the outcome: what is wrong with the behaviour you see? Do you get any error message? Does the tools or program stop without the expected output being created? Does the tools/program never stop? Etc.
- if you have an error message, please copy the full error message as much as possible. Do not copy only the last line for example.
- if you are producing a plot and the resulting plot is not what you expect, please explain how the plot you see is not correct. Simply attaching the plot as an image isn’t enough. You may think about adding some annotation directly to the plot to highlight the issue for example.
Using a template
There is a template available for creating a help request. When creating your topic select the “gear icon” and then select the “Insert template” menu item
which brings up a menu of available templates. Select the “Getting help template”
and it will pre-populate your topic with headings and helpful comments to guide you through the process of creating a help request
