We've moved!
This site is now read-only. You can find our new documentation site and support forum for posting questions here.
Be sure to read our welcome blog!

Help us help you: a note to those asking questions

shleeshlee CambridgeMember, Broadie ✭✭✭✭✭
edited June 2019 in Announcements


Here are some rules-of-thumb for posting questions

  1. Post a new question instead of continuing an ongoing discussion thread.
    The exception to this is if your question relates directly to the discussion thread, i.e. comments on the original post or answers a question asked in the thread. To refer to a particular thread, you can include its URL.

  2. Post the question once.
    This is the case even if you post to the wrong subforum. We can easily move your post to the appropriate one.

  3. Questions relate to running a GATK tool, Picard tool, GATK Best Practice Workflow, WDL script, Cromwell or Terra.
    All other questions, e.g. those about non-GATK tools, you should ask the Biostars or SeqAnswers forums.

Next, I point out specific guidelines for GATK questions, give a formatting tip and explain the motivation behind this note using pie.

Include enough context. For GATK, follow guidelines.

image You might feel caught in a catch-22 (of the double bind type, not of the 22q11.2 deletion syndrome) because if you knew something was helpful towards answering your question, you would include it. Rest assured, most of you get right to the point and provide sufficient context upfront that allows us to minimize the back-and-forth of clarifying details. We really appreciate that. To help in this matter, for our most active GATK forum, we now list specific guidelines on the side of the Ask a Question page. These are marked with pointing fingers (my mom told me it's rude too but I don't listen to her anymore). Click on the link and take a look.

An extremely useful formatting tip

Surround blocks of code, error messages and BAM/VCF snippets--especially content with hashes (#)--with lines with three backticks ( ``` ) each. This forms what is called a codeblock and I illustrate it further here.

Not only do codeblocks help us easily digest your post, they also help to avoid the collision between VCF/BAM format elements and the Markdown formatting that our website uses. 

Let me explain. Lines starting with any number of hashes, e.g. that of VCF and BAM headers, make for wonky fonts. You can end up with really large fonts that make it appear you are yelling. The DIY solution is to enclose these lines in codeblocks that display elements literally, without Markdown interpretation. If you experienced any consternation because of this collision, then perhaps now you can find it a bit funny, in the ironic sense that I do.


The time-pie constant

Improving the efficiency of the question-and-answer process helps in two ways that relate to a constant I call the time-pie.

  • First, consider the relationship between multitasking and productivity. In our case, a task is writing a thoughtful answer to a forum question, as @bhanuGandham does full-time for the GATK forum’s 3000 active participants. Switching from one task to another, without completing the first task, and performing tasks in rapid succession are two forms of multitasking. Such multitasking costs a lot of overhead that inefficiently spends mental reserves. We can be more effective when we focus on one task at a time, to completion. For both the pie-server and the pie-receiver, an eighth of a pie piece is better than three 1/24th pieces.

  • Second, the teams that field forum questions are the same teams that help improve tool documentation and write new content on the forum and for the workshops. The more time we spend going back and forth on questions, the less time we spend on these activities and on investigating questions in more depth. This is doubly so in that we often consult our developers on your behalf and thereby eat some portion of their time-pies.

Your questions are an integral part of our development process in that they allow us to check the pulse so to speak of how our tools perform. Many thanks for reading this and for being a part of our community.

Pie image from <https://commons.wikimedia.org/wiki/File:Steven's_Apple_Pie.jpg>.

Post edited by Geraldine_VdAuwera on
Sign In or Register to comment.