10
$\begingroup$

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.)

$\endgroup$
2
  • $\begingroup$ The boundary between general structuring and formatting and specific presentation points is fuzzy. Your answer is excellent, but I wouldn't have thought of referencing as being a general presentation matter. Other way round, areas in which many posts allow improvement include trimming content (apologies for question, thanks in advance, gratuitous context, pleas of urgency or desperation) and presentation of mathematics, code and data --- but I'd see all of these as specific. $\endgroup$
    – Nick Cox
    Feb 6 at 18:02
  • $\begingroup$ @NickCox: That is a good point. I have edited the question to ask more generally about any best practices for editing to improve a post. I don't wish to get hung up on scope, so answers that address any kind of good edits are welcome. $\endgroup$
    – Ben
    Feb 19 at 0:38
9
$\begingroup$

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 Peterson (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?

$\endgroup$
5
  • 4
    $\begingroup$ I don't quite agree that external references that are only said to be "not helpful" are always, well, not helpful. Quite often, there is some standard answer one would suggest, and if the OP explicitly points out they did think of this answer and why it does not help them in this particular instance can be very useful indeed (and also shows they did their homework). Otherwise very nice question and self-answer, +1! $\endgroup$ Feb 5 at 16:26
  • 2
    $\begingroup$ (+1) But I'd say enough bibliographic detail ought to be included to enable the source still to be found if the link breaks. And there's a case for including the titles of articles or books so someone can come across them by searching the site. $\endgroup$ Feb 6 at 15:18
  • 3
    $\begingroup$ (+1) Excellent. A pet peeve of mine is references to a lengthy video with no detail on when in the video something is discussed. $\endgroup$
    – Nick Cox
    Feb 6 at 17:05
  • $\begingroup$ A pet peeve of mine is that to understand a question, you must be able to say Table 4 in the linked paper. But the paper is behind a paywall. $\endgroup$ Feb 14 at 1:02
  • $\begingroup$ @Scortchi: Regarding giving bibliographic information in case the link breaks: I think this depends on the stability of the link. For most academic papers there is a stable JSTOR link that is likely to be a permanent feature of the internet. In these cases I tend to think that the Harvard-style citation with a link is enough, and additional bibliographic detail is then just a distraction. Nevertheless, I concede that this is a subjective issue, and others might disagree. $\endgroup$
    – Ben
    Feb 19 at 0:31
2
$\begingroup$

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.

  • 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 package. 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. 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)
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)
set.seed(1)
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)
$\endgroup$
2
  • 2
    $\begingroup$ (+1) Excellent as before. I'd add that a surprisingly common omission is not even to name the language or environment being used, which never hurts and often helps. (The common implication "obviously, I use R" is insensitive.) $\endgroup$
    – Nick Cox
    Feb 18 at 12:28
  • $\begingroup$ As for "You may assume that the user has the relevant software and has downloaded all required packages", well, you can assume the moon is made of chocolate but wishing doesn't make it so. More seriously, I would want to see a firmer overall stance that (1) code should be illustrative of a statistical problem; questions mostly about code are usually off-topic (2) the more you assume that readers should run software to see what the problem is, the less likely good answers will be. $\endgroup$
    – Nick Cox
    Feb 18 at 12:29

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .