Skip to content

Latest commit

 

History

History
160 lines (137 loc) · 8.97 KB

CONTRIBUTING.md

File metadata and controls

160 lines (137 loc) · 8.97 KB
Raw
layout title permalink
page
Contributing
/contributing/
XKCD cartoon on clinical trials

Contributions to this site are very welcome. Our aim is to strengthen ties between research and practice, so please write in the style of a popular science article rather than in dry academic prose. (This article from American Scientist is a good example.) Our focus is software engineering, with some ventures into software architecture and computing education. We prefer that people do not review their own work (though we welcome reviews of adjacent work), and the final decision on contributions will be made by the current editor; we would be happy to talk with you about specifics and give feedback on drafts.

All contributors must abide by our [Code of Conduct]({{'/conduct/' | relative_url}}). By submitting material to this site, you agree that we may publish it under the terms of the [Creative Commons - Attribution License (CC-BY)]({{'/license/' | relative_url}}).

Guidelines

  1. *Would you express your opinion so strongly if the paper had come to the opposite conclusion? For example, if it had found that doing X actually did improve code quality, or that Y wasn't better than Z, would you write the same way?
  2. Are you criticizing the paper's actual claims? If it says that P holds for novices who are learning how to program, there is no point saying, "But no experienced programmer would do that!"
  3. Are your criticisms of the paper's statistics valid? It's meaningless to say, "The paper's sample size is too small," without some quantification.
  4. Are you employing proof by rhetoric? The statement, "It's obvious that J," is verbal bullying, not proof. And many "obvious" things aren't actually true: that's why we do studies.

For Faculty and Students

We encourage faculty to have students write popular summaries of papers as graded work in courses and to submit them to this site. To avoid ethical concerns, we recommend that:

  1. Students be told that their work can be submitted, but that this is not a course requirement and that whether or not they do this will not affect their grade.
  2. Students do not indicate whether or not they're going to submit their work to this site until after it has been graded.

If your institution or your legal jurisdiction requires submissions to be handled in some other way, please get in touch; we'd be happy to try to accommodate you.

How to Contribute

  1. Fork this repository on GitHub.
  2. Create a branch with a name like author-year-short-title, e.g., wilson-2021-example-subject. Please use the surname of the paper's first author as the author field and a four-digit year.
  3. If your paper is already in tex/todo.bib, move the entry to tex/nwit.bib. If you have chosen another paper, please enter its DOI into https://doi2bib.org/ and copy that BibTeX into tex/nwit.bib. Please remember to copy the paper's abstract into the abstract field.
  4. Copy ./_template.html to create _posts/YYYY/YYYY-MM-DD-short-title.html, where YYYY-MM-DD is the date of your post (not the publication date of the paper) and short-title matches the short title of your branch (e.g., example-subject).
  5. Fill in the HTML file (see below).
  6. When you are done, create a pull request from your repository to this one and email us to let us know your post is ready for review. Please also let us know what URL to use for you in the acknowledgments.

When filling in the HTML template:

  1. Replace Your Name with the name you would like to appear in the review. Please note that we do will only accept anonymous or pseudonymous reviews by prior agreement: get in touch if you want to do this.
  2. Replace Paper Title with the paper's title (in double quotes).
  3. Replace YYYY-MM-DD with the post's publication date (which should match the first part of your file's name).
  4. Replace the list of categories with ones appropriate to your paper. Please use [existing categories]({{ '/category/' | relative_url }}) if you can rather than adding new ones.
  5. Replace all occurrences of BibliographyKey with the BibTeX key of the paper you are reviewing and fill in the bibliographic details inside the paragraph block. We will reformat this for you if necessary when we merge your pull request.
  6. Copy the full abstract of the paper into the blockquote below the citation. If the abstract is written as several paragraphs in the paper, please preserve that formatting.
  7. Finally, write your review in the div below the abstract.

But Wait, There's More

You (or your students) can also submit short explanations of the methods most commonly used in software engineering research, with examples that use software engineering data—something like Statology's explanation of the Mann-Whitney test but with SE data, or an explanation of similar length and depth of something like the card sorting used in many qualitative studies (again, using data from software engineering or computing education studies). Note that while we think the tidyverse is more approachable than Pandas for people new to programming, computer scientists and software engineers are more likely to already know Python, so we prefer it for code examples. We can translate for you if necessary.

Acknowledgments

Our entries have been written by:

We are also grateful to Shashi Kumar and Bailey Harrington for help with LaTeX.

Colophon

Our Jekyll theme is based on Dominic Elayda's Celeste. We rely heavily on David Graf's doi2bib.org, the Semantic Scholar API, and the work of Alexandra Elbakyan to find papers and obtain bibliography entries for them. We use Plausible Analytics to collect traffic statistics without using cookies or any gathering personal identifying information: please see their website for details.

A Footnote on Comments

In the wake of Greg Wilson's posts on his personal blog about Shopify's support for white nationalists and DataCamp's attempts to cover up sexual harassment we had to disable open comments on sites he contributes to. Please email us if you'd like to add a comment on any of the posts on this site.