What are some "best practices" for editing to improve a post?

Question

We already have another excellent question on CV.SE setting out editing dos and don'ts, but that mostly focuses on the limitations that apply to editing other people's posts, rather than the substance of what are some good practice for editing to improve a post. The purpose of the present question is to elicit some general recommendations on how to improve posts on CV.SE using standard editing methods. This will be of use for the benefit of both original posters and editors. We have many excellent contributors here who have learned a lot of good ways to structure and format their posts, and edit to improve the clarity, so I think it would be valuable to list some proposed "best practices" or tips for other users.

(Caveat: I am aware that there are different considerations depending on whether one is formatting one's own post or a post written by another user. In the latter case, it is established practice on CV.SE that edits should not change the substance of the original post, or even correct statistical errors in the original post. Advice on "best practices" should take this as given.)

Answer 1

Improve external references and add hyperlinks

CV.SE questions and answers should be self-contained, but often they will refer to external material such as academic papers, course notes, blog posts, software programs or packages, other questions/answers on SE, etc. Improving external references and adding hyperlinks can simplify the formatting of a question or answer, and it is convenient for readers to have direct links to the source material. Here are some tips for "best practice" with regard to improving external references:

• Only include external references when they add something: Sometimes we see posts where the poster makes a gratuitous reference to external material only to tell us it was not helpful. That is rarely something that adds value to the question or answer. When giving external references, check if they actually add anything of value to the post, and take them out if they do not.

• Consider adding Wikipedia links for concepts/objects/rules in probability and statistics: Most basic concepts, objects and rules in probability and statistics have their own page on Wikipedia, and the quality of these pages is usually quite good. It can be helpful to add links from these pages when writing a question or answer in order to assist users who might be unfamiliar with some of the material. This is particularly helpful when giving answers that invoke a particular concept or rule in probability or statistics that the questioner, or other similar readers, may be unfamiliar with.

• Have a clear textual citation/description and a hyperlink: References to academic papers, course notes, blog posts, etc., are sometimes made without a clear reference or link, or with a textual web address in place of a reference/link. A good external reference will give the name of the linked item (e.g., a simple citation or a description of the item) and a hyperlink that links to a stable source for that item. References to external material do not require full bibliographic details, since the link itself gives access to the full details; consequently, it is best to give a reference in a simple format (e.g., Harvard style references to papers) and let the hyperlink take care of the rest.

• Replace textual web addresses with hyperlinks: Unless there is a compelling reason to the contrary, textual web addresses should always be changed to hyperlinks. Textual web addresses are ugly and distracting, and they are unnecessary given the ability to hyperlink text.

• Give page numbers, direct quotations, etc., where necessary: As with citations in academic papers, all external links should give sufficient detail to find the source of any referenced material. If you quote from an external document you should use quotation marks to indicate a direct quote. If you link to a document and quote from that document, or paraphrase a particular part of the document, you should include a page number in the reference (if it has page numbers) to allow the reader to identify the specific part containing the quoted/paraphrased material.

• Rephrase statements saying "I have read ...": Sometimes references to external materials will be given in way where the description focuses on the fact that the poster has read the material, rather than focusing on the substance of what is in the material. For example, a post might say something like, "I have read X and they say Y." This is unnecessary, since the reader may take for granted that if you cite a reference and describe its content, then presumably you have read it. Thus, it is generally preferable to reduce "I have read X and they say Y" to something simpler like "X says Y". In cases like this it is usually possible to edit to give a more parsimonious description that focuses on the substance of what is in the external material at issue.

In the section below I show an example of a bad version of a question that uses poor practices for structure and formatting of external material, and then an edited version that applies the above practices.

---

Bad version:

This question is about robustness testing in linear regression analysis. I consulted my lecture notes on this for my linear regression course, but they weren't any help --- they don't say much about robustness. Aside from my lecture notes, I was reading this paper at https://www.jstor.org/stable/2345881?seq=1 where the authors look at methods for robustness in regression modelling, and they have some useful technical material for how to do robustness testing in this context. However, I also saw on Andrew Gelman's blog that he has a post where he comments on the limitations of robustness testing, and he says that robustness tests are typically to confirm your beliefs, which is typically a bad game to play.

How do I reconcile the use of robustness procedures in academic literature to the concerns expressed by Gelman?

Good version:

This question is about robustness testing in linear regression analysis. Carroll and Pederson (1993) look at methods robustness in regression modelling, and they have some useful technical material for how to do robustness testing in this context. However, this post on Andrew Gelman's blog comments on the limitations of robustness testing. In particular, he says that "[p]art of the problem is that robustness checks are typically done for purpose of confirming one’s existing beliefs, and that’s typically a bad game to be playing."

How do I reconcile the use of robustness procedures in academic literature to the concerns expressed by Gelman?

Answer 2

Trim gratuitous content in questions (and make the question clear)

Questions on CV.SE may contain unnecessary content that distracts from the substance of the question. This excess content can make it harder to see the question at issue. Common forms of gratuitous content include preliminary apologies for lack of understanding, thanks for attention to the question, or pleas of urgency (hat-tip to Nick Cox for pointing this out in comments). The description of StackExchange clearly states that "This site is all about getting answers. It's not a discussion forum. There's no chit-chat."

• Remove apologies and thanks: If the question contains any preliminary apology or self-effacement for lack of understanding, or thanks-in-advance for attention or answers, these should generally be removed. It is not necessary for users to apologise for lack of understanding of statistical material.

• Remove pleas of urgency or attention: Not only is this content gratuitous, but it also solicits special attention to a question. Such content does not advance the goal of giving a clear question or constructing long-term value for the site.

• Remove gratuitous context: Sometimes context is useful to understand the substance of a question, but in some cases it is gratuitous. Care should be taken to distinguish these cases, but if gratuitous context is added, this can often be trimmed or removed.

• Make the question clear and prominent: In some cases the question at issue is hidden among other material and it is difficult for the reader to find. If the question is buried inside large amounts of contextual content, or if the question is only implicit, it can take multiple readings of the question to understand what is being asked. In such cases it is useful to make the question more prominent and make it explicit. This can be done by explicitly marking the question at the end of the required context (an example of this technique is shown here).

• Don't change the substance of the question, or remove a preliminary confusion: When trimming gratuitous content from questions, it is important not to change the substance of the question. This includes ensuring that you do not remove preliminary assertions that are confused or false, since those parts constitute areas where the questioner may need a response that corrects their preliminary misunderstandings. Care should be taken to determine when gratuitous material can be trimmed without altering the substance of the question. If in doubt, ping the OP to draw attention to your changes and ask if this still captures the essence of their question.

---

Bad version: Hi everyone. Sorry if this post doesnt make sense but I'm not a statistics expert and I only did a few simple courses many years ago. I really need help on this for a project and my boss is putting pressure on me to get it done, so I really need an answer quickly! I'm doing analysis where x and y are whole numbers and I did linear regression. All good so far and I got results, but a collegue said you can't use linear regression for whole numbers. I need to figure out if there is a relationship so then I used correlation. Correlation is 0.3341 so it confirmed a relationship. Collegue is still not happy with it and says correlation is also not good for whole numbers. Ive looked at lots of other posts on regression and I can't figure out what to do when my variables are correlated by they are whole numbers also. My x is number of days of TV advertising for companies and my y is number of offices for company. I want to look at relationship with sales revenue maybe and I have another variable for this. Maybe I need to add this in too but first I am doing this other part. Thanks in advance for helping me! If I can know how these things affect sales revenue I will make my boss happy! I'm going to do more statistics courses later to learn this but at the moment I don't know it well, so thanks for attention.

Good version: I am examining advertising and sales for companies. I have a dataset containing data for companies, with variables for the sales revenue, the number of offices, and the number of days of TV advertising. I want to know the effect of advertising days on sales revenue. So far I have fit a linear regression between number of offices and advertising days and I have also computed the correlation between these variables. However, I have been told that linear regression and correlation are not suitable for whole number variables. What should I do to determine the effect of the other two variables on sale revenue?

Answer 3

Improve references to computer code, software, packages, functions, etc.

Questions and answers on CV.SE will often refer to computer code, software, packages, or individual functions. That might include full chunks of code for implementation of statistical methods discussed in the post, or it might include in-text references to packages and functions that are useful for the methods. Here are some tips for "best practice" with regard to improving these aspects of a post:

• Use computer-code font for all references to code, software and packages: Full code chunks are automatically shown using computer-code font but it is also desirable for in-text references to these things to appear in this font. (You should also make sure you use correct capitalisation of names of packages and functions in any software applications that are case-sensitive.) This assists the reader in seeing which aspects of the discussion pertain to software implementation, and it also ensures that references to packages and functions appear in a consistent font both in the body of the text and in any accompanying code chunks.

• State what language you are using: This may seem an obvious point, but sometimes posters forget to specify the language they are using for their code (e.g., Python, R, Stata, etc.). Many experienced coders will recognise the language, but not all users will. Best practice here is to explicitly state the coding language you are using.

• Add relevant external links for packages and functions: When giving an in-text reference to a package for a piece of statistical software, it is desirable to give an external link to the relevant documentation for the package. When giving an in-text reference to a function, it is desirable to give an external link to the page showing the information for that function (e.g., function arguments, output, description, examples, etc.). You only need to do this once, so that the reader has a link to relevant documentation, so don't feel the need to link over and over again if you mention a package or function multiple times. Links may not be necessary for functions and packages that are in common use, but they are extremely helpful for obscure functions or packages. For packages in R you can link to their page in CRAN and for functions in R you can link to their information pages at rdrr.io or the UPenn R help pages. These sources give useful links for readers to help them understand the syntax used for a package or function.

• Make sure your code runs and is replicable: When you give chunks of computer code you should check to make sure that your code runs on a newly loaded console, without any other preliminary commands that have not been included. You may assume that the user has the relevant software and has downloaded all required packages, but you need to remember to include commands to load relevant packages if you are using functions from them. If you are doing randomisation then you should also "set the seed" to ensure that any pseudo-random numbers generated in the code are replicable. If you include graphical output in your post then you should make sure that the graphical output you give is what is produced in your code. (There may be some cases where you give a graph without showing the code, in which case this does not apply.)

• Use proper annotation in chunks of computer code: Even though questions and answers will usually have some accompanying text giving context to any relevant computer code, it is still good practice to ensure that chunks of code are annotated with labels that break up the parts into manageable chunks, and tell the reader what the parts of the code are doing. As a general rule, the code should not be out of place in an application where the user does not have access to the original question/answer.

• Avoiding hard-coding specific parameter values in code: Many questions on CV.SE ask for the answer to a specific statistical question with a particular set of parameters. Notwithstanding this fact, the goal of answers is to be broadly applicable to variations of the question that might be of interest to other readers. This means that when giving computer code for answers, it is often useful to separate out the specific parameter values used for the particular question from the general form of the code to get the answer. Rather than "hard-coding" the parameter values, instead add a line of code defining each relevant parameter value and then reference these values in the code. This makes it easier for readers to substitute other parameter values if they want to apply your method to their own problem.

• Use helpful names for things in code: Ideally, all variables and other objects in your code should have names that bear a close resemblance to their actual content, or to the notation usually used to represent them in statistical discussions. For small pieces of code it is usually possible to name your objects in a helpful way, but this may become cumbersome if you have a long piece of code with many intermediate objects, so some reasonable judgment is needed. In any case, consider naming your data as DATA and your model as MODEL and so on, to make it obvious to the reader what these objects are. In programs like R that are case-sensitive, one useful thing you can do is to name your objects with upper-case and then have these roughly match up with argument inputs of functions which are written in lower-case (e.g., if you have a function that takes an input slope then create a variable SLOPE for its value and then input it to the function as slope = SLOPE).

In the section below I show an example of a bad version of a question that uses poor practices for coding, and then an edited version that applies the above practices.

---

Bad version:

You can implement Kaplan-Meier using bootstrap methods with the bootkm function in hmisc, but you will need to set $q = 0.8$ because that is not the default. Here is how you do this with one-hundred bootstrap repetitions for a test of quantile difference for a variable for males and females:

S <- Surv(runif(400))
dd <- data.frame(var = S, type = c(rep('M', 200), rep('F', 200)))
ssm <- bootkm(a['type' == 'M'], b = 100, q = 0.8)
ssf <- bootkm(a['type' == 'F'], b = 100, q = 0.8)
describe(ssm-ssf)
quantile(ssm-ssf)

Good version:

You can implement Kaplan-Meier using bootstrap methods with the bootkm function in the Hmisc package in R. The function takes an input q for the quantile, so you will need to set this to your desired value. The function also takes an input b for the number of bootstrap iterations (500 by default), but we will only use 100 iterations. Here is how you perform 100 bootstrap iterations for a test of quantile difference for the survival time for males and females in a mock set of data (where the true difference is zero):

# Load required libraries
library(survival)
library(Hmisc)

# Create some mock survival data (using the survival package)
# Survival times for a sample of males (M) and females (F)
set.seed(1)
n <- 400
TIME <- Surv(runif(n))
DATA <- data.frame(Time = TIME, Sex = c(rep('M', 200), 
                    rep('F', 200)))

# Perform the bootstrap iterations (using the Hmisc package)
QUANTILE    <- 0.8
ITERATIONS  <- 100
BOOT.MALE   <- bootkm(DATA[DATA$Sex == 'M', ], b = ITERATIONS, 
                  q = QUANTILE)
BOOT.FEMALE <- bootkm(DATA[DATA$Sex == 'F', ], b = ITERATIONS, 
                      q = QUANTILE)

# Describe the quantile difference
describe(BOOT.MALE-BOOT.FEMALE)
quantile(BOOT.MALE-BOOT.FEMALE)