16  Colophon

Authors
Affiliations

Shawn O’Neil

William H Beasley

Johanna Loomba

Sharon Patrick

Kenneth J. Wilkins

Karen Crowley

A Jerrod Anzalone

16.1 How the Guide Came To Be

While N3C leverages a variety of existing technologies, many of the tools, processes, and organizational structures were developed for its unique needs, resulting in a complex landscape for researchers to navigate. The idea for a comprehensive guide was originally proposed in January 2022 by members of the Education and Training Domain Team, with the first public release presented at the May 2023 N3C Community Forum. Drawing inspiration from the Book of OHDSI, its creation involved many volunteers and required coordination across a wide variety of stakeholders, contributors, and subject matterexperts. This chapter outlines the processes involved, in the hope it may benefit others.

The Guide exists within a larger landscape of educational and training materials, both from within the N3C community and the larger health data sciences oeuvre. The overarching goal was the creation of a living textbook that serves as a single entry point to engaging with the Enclave. As such, the development focused on leveraging existing content, providing a cohesive information structure, and filling in crucial gaps based on a learning community of users and stakeholders.

16.2 Editorial Committee, Ideation, and Outlining

Because N3C is a large consortium, project members first set out to establish an Editorial Committee representing a broad set of stakeholder groups and other teams. These included:

Editorial Committee members were invited to maximize coverage of these groups with an eye toward keeping the Committee small and efficient.

The Committee’s initial focus was 1) identifying audiences: current or potential researchers primarily, and organizers of other large community efforts secondarily, and 2) identifying the set of topics to be covered. To do so in an inclusive and impartial manner, each Committee member independently generated a list of topics for inclusion. These were then organized into thematic areas to highlight topics of widespread interest as well as important niche subjects.

initial-topics-organized Having compiled a set of topics, the Committee then created a preliminary outline, which included chapter and subsection titles along with brief notes on the proposed content. This outline was shared with the broader N3C community through mailing lists, the Domain Team leads, and other communication channels to solicit feedback. Although no significant changes or additions were suggested, the inclusion of several smaller topics and minor reorganization helped to enhance the overall structure of the outline, as well as generate community interest.

16.3 Drafting Chapters

16.3.1 Roles and Responsibilities

For each chapter, one or more subject matter experts were invited to act as chapter leads. Chapter leads were encouraged to recruit additional contributors as authors, while primarily overseeing the development of chapter content. The Editorial Committee was responsible for facilitating communication, organization, and publication processes. They also ensured the coherence, quality, and suitability of the final product, collaborating closely with chapter leads as necessary.

The Committee monitored chapter progress on a monthly basis, and organized writing sessions, office hours, and communication channels to foster cross-chapter discussions and address contributor questions.

16.3.2 Content Guidance

To ensure a consistent presentation and flow throughout the Guide, the Editorial Committee created a guidance document for contributors offering style and technical advice, encouraging:

  • Linking to external sources of truth when available
  • Audience-focused content
  • Prose over bulleted lists (except where appropriate)
  • Ample use of high-resolution screenshots and examples
  • Common elements like info-boxes
  • References, cross-references, and footnotes
  • Appropriate attribution
  • Minimizing references to resources with restricted availability

This guidance also detailed the roles and responsibilities described above, and provided links to the draft outline and other resources as a central information source for contributors.

16.3.3 Technical Considerations

The Committee decided early in the project to publish via a technical stack based on GitHub pages and the markdown-based Quarto package. However, as many authors were unfamiliar with these technologies, all draft content was initially created in Google Docs to facilitate collaborative editing and ease of contribution. Each chapter team was provided with a “stub” document linking to the guidance document, all within an organized folder structure.

Contributors were required to upload high-resolution images following a suggested file naming convention for eventual publication. They were also encouraged to include cross-references between chapters, which was complicated by the parallel development of chapter content across teams. Instead of linking directly to other sections, contributors included ‘pseudo-links’ to anticipated chapters and subsections indicated by the draft outline, which needed to be finalized during the publication process.

16.4 Review and Publication

As each chapter was completed, the Committee designated three peer reviewers to evaluate the content for accuracy and appropriateness. These reviews were openly conducted within the Google Doc drafts using commenting and suggesting features. Editorial Committee members frequently served as reviewers for many chapters (excluding those they authored), but other subject matter experts were also engaged.

After reviews were completed content was migrated to GitHub and published in proof form. While part of this process was automated, considerable manual effort was required to curate references to external sources, cross-references between sections, and other metadata. GitHub issues and checklists were used to track each chapters’ publication progress, in close collaboration with chapter leads.1

As a living document, changes and new content are managed via GitHub, with needs tracked via issues. See the How to Contribute section for details.

16.4.1 Software and Rendering Configuration

This section is automatically generated and details the Quarto and R configuration used in rendering.

─ Session info ───────────────────────────────────────────────────────────────
 setting  value
 version  R version 4.4.1 (2024-06-14)
 os       Ubuntu 22.04.4 LTS
 system   x86_64, linux-gnu
 ui       X11
 language (EN)
 collate  C.UTF-8
 ctype    C.UTF-8
 tz       UTC
 date     2024-07-01
 pandoc   2.9.2.1 @ /usr/bin/ (via rmarkdown)

─ Packages ───────────────────────────────────────────────────────────────────
 package     * version date (UTC) lib source
 cli           3.6.3   2024-06-21 [1] CRAN (R 4.4.1)
 digest        0.6.36  2024-06-23 [1] CRAN (R 4.4.1)
 evaluate      0.24.0  2024-06-10 [1] CRAN (R 4.4.1)
 fastmap       1.2.0   2024-05-15 [1] CRAN (R 4.4.1)
 htmltools     0.5.8.1 2024-04-04 [1] CRAN (R 4.4.1)
 jsonlite      1.8.8   2023-12-04 [1] CRAN (R 4.4.1)
 knitr         1.47    2024-05-29 [1] any (@1.47)
 rlang         1.1.4   2024-06-04 [1] CRAN (R 4.4.1)
 rmarkdown     2.27    2024-05-17 [1] CRAN (R 4.4.1)
 sessioninfo   1.2.2   2021-12-06 [1] any (@1.2.2)
 xfun          0.45    2024-06-16 [1] CRAN (R 4.4.1)
 yaml          2.3.8   2023-12-11 [1] CRAN (R 4.4.1)

 [1] /home/runner/work/_temp/Library
 [2] /opt/R/4.4.1/lib/R/site-library
 [3] /opt/R/4.4.1/lib/R/library

──────────────────────────────────────────────────────────────────────────────
$quarto
$quarto$version
[1] "1.4.557"


$dir
[1] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1"

$engines
[1] "markdown" "knitr"   

$config
$config$project
$config$project$type
[1] "book"

$config$project$`lib-dir`
[1] "site_libs"

$config$project$`output-dir`
[1] "_book"

$config$project$render
 [1] "index.qmd"                 "chapters/intro.md"        
 [3] "chapters/story.md"         "chapters/cycle.md"        
 [5] "chapters/governance.md"    "chapters/onboarding.md"   
 [7] "chapters/access.md"        "chapters/understanding.md"
 [9] "chapters/tools.md"         "chapters/practices.md"    
[11] "chapters/publishing.md"    "chapters/support.md"      
[13] "chapters/ml.md"            "chapters/upcoming.md"     
[15] "chapters/funding.md"       "references.qmd"           
[17] "chapters/colophon.qmd"    


$config$bibliography
[1] "references.bib"

$config$`google-scholar`
[1] TRUE

$config$format
$config$format$html
$config$format$html$theme
$config$format$html$theme$light
[1] "assets/theme-light.scss"  "assets/tables-light.scss"
[3] "zephyr"                  

$config$format$html$theme$dark
[1] "assets/theme-dark.scss"  "assets/tables-dark.scss"
[3] "slate"                  


$config$format$html$css
[1] "assets/font-awesome.css" "assets/tables.css"      

$config$format$html$`link-external-newwindow`
[1] TRUE

$config$format$html$`title-block-banner`
[1] "images/g2n3c-banner-1.png"

$config$format$html$`title-block-banner-color`
[1] "#FCB754"

$config$format$html$filters
[1] "lightbox"

$config$format$html$lightbox
$config$format$html$lightbox$match
[1] "auto"

$config$format$html$lightbox$effect
[1] "zoom"



$config$format$epub
$config$format$epub$`cover-image`
[1] "images/logo.png"



$config$book
$config$book$title
[1] "The Researcher's Guide to N3C"

$config$book$subtitle
[1] "A National Resource for Analyzing Real-World Health Data"

$config$book$date
[1] "last-modified"

$config$book$doi
[1] "10.5281/zenodo.7306581"

$config$book$`cover-image`
[1] "images/n3c_logo_slim.png"

$config$book$`cover-image-alt`
[1] "images/n3c-logo-circle-large-0.png"

$config$book$favicon
[1] "images/n3c-logo-circle-large-0.png"

$config$book$`repo-url`
[1] "https://github.com/national-covid-cohort-collaborative/guide-to-n3c-v1"

$config$book$`repo-branch`
[1] "main"

$config$book$`repo-actions`
[1] "edit"   "issue"  "source"

$config$book$sharing
[1] "twitter"  "facebook"

$config$book$downloads
[1] "epub"

$config$book$`google-analytics`
[1] "G-5F685V8M7X"

$config$book$`page-footer`
$config$book$`page-footer`$left
[1] "<a href=\"https://ncats.nih.gov/n3c/\">N3C</a> &copy; <a href=\"https://creativecommons.org/licenses/by-nd/4.0/\"> CC BY-ND 4</a>\n"

$config$book$`page-footer`$right
[1] "Part of <a href=\"https://covid.cd2h.org/\">NIH NCATS</a>.\n"


$config$book$editor
               name                                   affiliation
1 William H Beasley University of Oklahoma Health Sciences Center
2      Shawn O'Neil              University of Colorado, Anschutz
             affiliation-url                 email               orcid
1    https://ouhsc.edu/bbmc/ wibeasley@hotmail.com 0000-0002-5613-5006
2 https://oneilsh.github.io/     oneilsh@gmail.com 0000-0001-6220-7080

$config$book$chapters
$config$book$chapters[[1]]
[1] "index.qmd"

$config$book$chapters[[2]]
$config$book$chapters[[2]]$part
[1] "Getting Started"

$config$book$chapters[[2]]$chapters
[1] "chapters/intro.md"      "chapters/story.md"      "chapters/cycle.md"     
[4] "chapters/governance.md" "chapters/onboarding.md"


$config$book$chapters[[3]]
$config$book$chapters[[3]]$part
[1] "Investigating"

$config$book$chapters[[3]]$chapters
[1] "chapters/access.md"        "chapters/understanding.md"
[3] "chapters/tools.md"         "chapters/practices.md"    
[5] "chapters/publishing.md"   


$config$book$chapters[[4]]
$config$book$chapters[[4]]$part
[1] "Special Topics"

$config$book$chapters[[4]]$chapters
[1] "chapters/support.md"  "chapters/ml.md"       "chapters/upcoming.md"


$config$book$chapters[[5]]
$config$book$chapters[[5]]$part
[1] "Back Matter"

$config$book$chapters[[5]]$chapters
[1] "chapters/funding.md"   "references.qmd"        "chapters/colophon.qmd"



$config$book$render
      type                      file depth            text number
1  chapter                 index.qmd     0            <NA>     NA
2     part                      <NA>     0 Getting Started     NA
3  chapter         chapters/intro.md     1            <NA>      1
4  chapter         chapters/story.md     1            <NA>      2
5  chapter         chapters/cycle.md     1            <NA>      3
6  chapter    chapters/governance.md     1            <NA>      4
7  chapter    chapters/onboarding.md     1            <NA>      5
8     part                      <NA>     0   Investigating     NA
9  chapter        chapters/access.md     1            <NA>      6
10 chapter chapters/understanding.md     1            <NA>      7
11 chapter         chapters/tools.md     1            <NA>      8
12 chapter     chapters/practices.md     1            <NA>      9
13 chapter    chapters/publishing.md     1            <NA>     10
14    part                      <NA>     0  Special Topics     NA
15 chapter       chapters/support.md     1            <NA>     11
16 chapter            chapters/ml.md     1            <NA>     12
17 chapter      chapters/upcoming.md     1            <NA>     13
18    part                      <NA>     0     Back Matter     NA
19 chapter       chapters/funding.md     1            <NA>     14
20 chapter            references.qmd     1            <NA>     15
21 chapter     chapters/colophon.qmd     1            <NA>     16


$config$language
named list()

$config$website
$config$website$title
[1] "The Researcher's Guide to N3C"

$config$website$favicon
[1] "images/n3c-logo-circle-large-0.png"

$config$website$`repo-url`
[1] "https://github.com/national-covid-cohort-collaborative/guide-to-n3c-v1"

$config$website$`repo-branch`
[1] "main"

$config$website$`repo-actions`
[1] "edit"   "issue"  "source"

$config$website$sidebar
$config$website$sidebar$title
[1] "The Researcher's Guide to N3C"

$config$website$sidebar$contents
$config$website$sidebar$contents[[1]]
[1] "index.qmd"

$config$website$sidebar$contents[[2]]
$config$website$sidebar$contents[[2]]$section
[1] "Getting Started"

$config$website$sidebar$contents[[2]]$contents
[1] "chapters/intro.md"      "chapters/story.md"      "chapters/cycle.md"     
[4] "chapters/governance.md" "chapters/onboarding.md"


$config$website$sidebar$contents[[3]]
$config$website$sidebar$contents[[3]]$section
[1] "Investigating"

$config$website$sidebar$contents[[3]]$contents
[1] "chapters/access.md"        "chapters/understanding.md"
[3] "chapters/tools.md"         "chapters/practices.md"    
[5] "chapters/publishing.md"   


$config$website$sidebar$contents[[4]]
$config$website$sidebar$contents[[4]]$section
[1] "Special Topics"

$config$website$sidebar$contents[[4]]$contents
[1] "chapters/support.md"  "chapters/ml.md"       "chapters/upcoming.md"


$config$website$sidebar$contents[[5]]
$config$website$sidebar$contents[[5]]$section
[1] "Back Matter"

$config$website$sidebar$contents[[5]]$contents
[1] "chapters/funding.md"   "references.qmd"        "chapters/colophon.qmd"



$config$website$sidebar$style
[1] "floating"

$config$website$sidebar$tools
           text    icon
1   Source Code  github
2 Download ePub journal
3         Share   share
                                                                    href
1 https://github.com/national-covid-cohort-collaborative/guide-to-n3c-v1
2                                    /The-Researcher-s-Guide-to-N3C.epub
3                                                                   <NA>
                                                                                                                                  menu
1                                                                                                                                 NULL
2                                                                                                                                 NULL
3 twitter, facebook, Twitter, Facebook, https://twitter.com/intent/tweet?url=|url|, https://www.facebook.com/sharer/sharer.php?u=|url|


$config$website$`page-navigation`
[1] TRUE

$config$website$`google-analytics`
[1] "G-5F685V8M7X"

$config$website$`page-footer`
$config$website$`page-footer`$left
[1] "<a href=\"https://ncats.nih.gov/n3c/\">N3C</a> &copy; <a href=\"https://creativecommons.org/licenses/by-nd/4.0/\"> CC BY-ND 4</a>\n"

$config$website$`page-footer`$right
[1] "Part of <a href=\"https://covid.cd2h.org/\">NIH NCATS</a>.\n"




$files
$files$input
 [1] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/index.qmd"                
 [2] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/intro.md"        
 [3] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/story.md"        
 [4] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/cycle.md"        
 [5] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/governance.md"   
 [6] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/onboarding.md"   
 [7] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/access.md"       
 [8] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/understanding.md"
 [9] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/tools.md"        
[10] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/practices.md"    
[11] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/publishing.md"   
[12] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/support.md"      
[13] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/ml.md"           
[14] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/upcoming.md"     
[15] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/funding.md"      
[16] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/references.qmd"           
[17] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/chapters/colophon.qmd"    

$files$resources
[1] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/.nojekyll"

$files$config
[1] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/_quarto.yml"

$files$configResources
[1] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/references.bib"           
[2] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/assets/theme-light.scss"  
[3] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/assets/tables-light.scss" 
[4] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/assets/theme-dark.scss"   
[5] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/assets/tables-dark.scss"  
[6] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/assets/font-awesome.css"  
[7] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/assets/tables.css"        
[8] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/images/g2n3c-banner-1.png"
[9] "/home/runner/work/guide-to-n3c-v1/guide-to-n3c-v1/images/logo.png"          

  1. See this checklist as one example within the collection of chapter checklists. Special thanks to Committee member Will Beasley for his technical expertise and development of this publication workflow!↩︎