Working with a team

Authorship

Discuss author order and come up with said order from the beginning. It should be listed on the analysis plan so all contributors are aware of it. This includes ALERRT researchers and external collaborators. Authorship in RR projects requires substantive contribution. Every named author must have written portions of the document, conducted analyses, or developed plots, etc. Providing feedback does not constitute authorship, but those individuals should be listed in the acknowledgements.

Roles

Roles should be loosely laid out at the beginning of the project as well so each contributor knows what their time commitment will be. Generally, but not always, the lead author will serve as the project manager and ensure tasks are given an appropriate amount of time to complete. This role is vitally important so projects stay on task and avoid manuscript purgatory.

Collaborative writing

More times than not writing a manuscript is a team sport. The RR should draft the manuscript using Quarto whenever possible. There are three different options for drafting the manuscript in Quarto.

  • Trackdown (experimental)
  • Version Control
  • Lead author transfer from Word

The method chosen will depend on the makeup of the team. The RR is experimenting with using the Trackdown R package so external collaborators can make edits to a Google Doc version of the manuscript. If this is not available, the lead author will transfer text from a Word version of the manuscript.

Internal peer review

Once the manuscript has been completed, the lead author should utilize an AI tool to conduct a “peer review” of the manuscript. The prompt should explicitly ask the AI tool to provide a critical review. There will be review items that do not apply, that is okay. The point is for the AI tool to point out logical gaps, structural issues, unclear results/discussion points, and so on to improve the manuscript prior to submission. The lead author will post the peer review in the “admin” subdirectory and let the appropriate team member know which comments to address.

Sharing results

The lead author should work with analysts to summarize and present results from a project to the wider RR team prior to the formal write-up. This gives the team the opportunity to understand how the analysis is proceeding and help shape how results are communicated in the manuscript by providing feedback.