Merge pull request #234 from National-COVID-Cohort-Collaborative/colo…

…phon

add colophon content

chapters/colophon.qmd

@@ -1,38 +1,177 @@
 ---
+author:
+  - name: Shawn O'Neil
+    affiliation: University of Colorado, Anschutz
+    affiliation-url: https://oneilsh.github.io/
+    email: [email protected]
+    orcid: 0000-0001-6220-7080
+    attributes:
+      corresponding: true
+
+  - name: William H Beasley
+    affiliation: University of Oklahoma Health Sciences Center
+    affiliation-url: https://ouhsc.edu/bbmc/
+    email: [email protected]
+    orcid: 0000-0002-5613-5006
+
+  - name: Johanna Loomba
+    affiliation: University of Virginia, integrated Translational Health Research Institute of Virginia
+    affiliation-url: https://www.ithriv.org/directory
+    email: [email protected]
+    orcid: 0000-0003-3673-5423
+
+  - name: Sharon Patrick
+    affiliation: West Virginia Clinical and Translational Science Institute
+    affiliation-url: https://www.wvctsi.org/
+    email: [email protected]
+    orcid: 0000-0001-6535-2013
+
+  - name: Kenneth J. Wilkins
+    affiliation: National Institutes of Health
+    affiliation-url: https://www.nih.gov/
+    email: [email protected]
+    orcid: 0000-0003-0531-7165
+
+  - name: Karen Crowley
+    affiliation: Brown University
+    affiliation-url: https://bcbi.brown.edu/
+    email: [email protected]
+    orcid: 0000-0002-1995-6358
+
+  - name: A Jerrod Anzalone
+    affiliation: University of Nebraska Medical Center
+    affiliation-url: https://gpctr.unmc.edu/
+    email: [email protected]
+    orcid: 0000-0002-3212-7845
+
 csl: ../assets/csl/apa-7e.csl
 ---
 
 # Colophon {#sec-colophon}
 
-:::{.callout-note}
-This chapter is being drafted in Google Docs at
-<https://drive.google.com/drive/u/0/folders/13KdNp29Af9nU3CW2Jr5FuWtHjJFGPxbP>
-:::
+## How the Guide Came To Be {#sec-colophon-be}
 
-:::{.callout-warning}
-At this point, any edits to this chapter should be made in Google Docs.
-The current Markdown is for testing only.
-It is NOT the source of truth (yet).
-:::
+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](https://youtu.be/WI8TuiQKCWM?si=4X9F4YHF3IBhdNUI&t=1893). Drawing inspiration 
+from the [Book of OHDSI](https://ohdsi.github.io/TheBookOfOhdsi/), 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.
+
+
+## Editorial Committee, Ideation, and Outlining {#sec-colophon-ed-committee-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:
+
+* [The Education and Training Domain Team](onboarding.md#sec-onboarding-dts)
+* [Project Management and User Support](onboarding.md#sec-onboarding-team-role)
+* [Data and Logic Liaisons](support.md#sec-support-liaisons)
+* [Ingestion and Harmonization](cycle.md)
+* [Governance](governance.md)
+* The [Machine Learning](ml.md) Domain Team and [Applicable Data Methods and Standards](practices.md#sec-practices-overview) workstream
+* Other clinical [domain teams](onboarding.md#sec-onboarding-dts)
+
+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. 
+
+![A subset of organized topics proposed by editorial Committee members. Colors represent suggestions from different members. Each cluster was subsequently considered for inclusion and placement in a draft outline.](images/colophon/fig-colophon-010-topic-clouds.png){#fig-colophon-010-topic-clouds width=100% fig-alt="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.
+
+## Drafting Chapters {#sec-colophon-drafting-chapters}
+
+### Roles and Responsibilities {#sec-colophon-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.
+
+### Content Guidance {#sec-colophon-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.
+
+### Technical Considerations {#sec-colophon-technical}
+
+The Committee decided early in the project to publish via a technical stack based on 
+GitHub pages and the markdown-based [Quarto](https://quarto.org/) 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.
+
+## Review and Publication {#sec-colophon-review-and-pub}
 
+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.
 
-How the Guide Came To Be {#sec-colophon-be}
-------------------
+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.^[See this [checklist](https://github.com/National-COVID-Cohort-Collaborative/guide-to-n3c-v1/issues/138) 
+as one example within the [collection](https://github.com/National-COVID-Cohort-Collaborative/guide-to-n3c-v1/issues/58) of chapter checklists. Special thanks to Committee member Will Beasley for his 
+technical expertise and development of this publication workflow!]
 
-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](https://youtu.be/WI8TuiQKCWM?si=4X9F4YHF3IBhdNUI&t=1893).
-Drawing inspiration from [*The Book of OHDSI*](https://ohdsi.github.io/TheBookOfOhdsi/),
-the creation of this guide involved many volunteers and required coordination across a wide variety
-of stakeholders, contributors, and subject matter experts.
-This chapter outlines the processes involved, in the hope it may benefit others.
+As a living document, changes and new content are managed via [GitHub](https://github.com/national-covid-cohort-collaborative/guide-to-n3c-v1), 
+with needs tracked via [issues](https://github.com/National-COVID-Cohort-Collaborative/guide-to-n3c-v1/issues?q=is%3Aissue). See the [How to Contribute](#sec-welcome-contribute) section for details.
 
-...
 
+### Software and Rendering Configuration {#sec-colophon-software}
 
-Software Used to Render Book {#sec-colophon-software}
-------------------
+This section is automatically generated and details the Quarto and R configuration 
+used in rendering.
 
 ::: {.callout-caution collapse="true"}
 ## R Configuration