Ch 7: Overall structure

[luizaandrade]

Introduction

• Publishing a well-written paper, with a relevant contribution and a rigorous research design is still mandatory, but no longer enough
• After the reproducibility crisis, being transparent and replicable is key for research credibility
• This means publishing not only your results, but also the steps and inputs necessary to get to them
• If the project followed the guidelines outlined in this book, this should be a relatively easy process

Paper

• The paper needs to be a dynamic document
• The standard for this is TeX, because it allows inputs (tables, figures) to be updated as they are recreated, eliminating the need for copy-pasting and the risk of using out of date results
• It also allows for easy management of bibliography, and has packages for many journals
• It looks pretty as well, but unlike what people may say, that's is not the reason why it's preferred
• Because it's plain text, it can also be version-controlled through git
• Bibliography, dynamic document, synchronisation with dropbox, version control, formatting, no crashing, ... Tables can be done directly in the stata/r code using markdown, and then inserted as separate objects in the latex code. (#213)
• There are different ways to do this, including online editors such as overleaf, and desktop editor such as TeXStudio, TeXWorks, TeXMaker, etc.
• Using markdown in R or Stata is also an option, as are the different formats offered by pandoc
• You can choose the format that best fits your needs, it just needs to be dynamic
• It can be often difficult to have all the authors use Latex or overleaf if they are not used to it for collaborative work,a second best option could be using latex / overleaf for the tables / figures (easier to format and to ensure reproducibility) and word to write the text, comment, tracking changes, and in a final step use the tools cited below to transfer the text in latex and add the bibliography (#213)
• Maybe also useful to mention that overleaf and latex have a lot of online documentation and maybe a link to some guide/lesson to start using latex or overleaf. (#213)

Replication package

This is well developed in the current text, but could also include

• Code review (you wouldn't submit the written paper without review, why would you do it with the code?)
• Documentation (as much as possible, including survey instruments, enumerator manual, list of variables, or list of data sources for secondary data)
• Code for cleaning and construction can also be included (for transparency, even if it will not be possible to run it)

Data publication

• Create a data citation
• How it's different to publish the raw data and the final data
• Disclosure issues
• If not possible to release the data, describe the process the research went through to get it, or what others would have to do to access it, and release metadata

Other references

• The Plain Person's Guide to Plain Text Social Science
• There are a lot of websites that translate directly word / excel in latex code. This app (https://mathpix.com/) can be really useful to get the latex code of equations, it even works for handwritten equations, it is really impressive. (#213)
• LaTeX Table Generator
• DIME LaTeX training

[kbjarkefur]

-Introduction
-- Collaborating on technical writing
--- What are dynamic documents?
          - What makes them dynamic? 
          - Why?
--- LaTeX
          - the industry standard
          - end with a quick getting started guide on overleaf
--- Other dynamic documents
-- Replication package
-- Data publication

[bbdaniels]

Reduced to https://github.com/worldbank/d4di/issues/348?