diff --git a/R/Episode.R b/R/Episode.R
index 689910a..7ad5d62 100644
--- a/R/Episode.R
+++ b/R/Episode.R
@@ -2,9 +2,16 @@
 #'
 #' @description
 #' Wrapper around an xml document to manipulate and inspect Carpentries episodes
+#' 
 #' @details
-#' This class is a fancy wrapper around the results of [tinkr::to_xml()] and
-#' has method specific to the Carpentries episodes.
+#' The Episode class is a superclass of [tinkr::yarn()], which transforms 
+#' (commonmark-formatted) Markdown to XML and back again. The extension that
+#' the Episode class provides is support for both [Pandoc](https://pandoc.org) 
+#' and [kramdown](https://kramdown.gettalong.org/) flavours of Markdown. 
+#' 
+#' Read more about this class in `vignette("intro-episode", package =
+#' "pegboard)`.
+#' 
 #' @export
 Episode <- R6::R6Class("Episode",
   inherit = tinkr::yarn,
@@ -99,7 +106,12 @@ Episode <- R6::R6Class("Episode",
       self$yaml <- ep$yaml
       self$body <- ep$body
       self$ns   <- ep$ns
+      # if the parents are missing, this walk will do nothing
       purrr::walk(parents, function(parent) add_parent(self, parent))
+      # the parent here is used to determine the build path for the
+      # child document, which is dependent on the build parent, aka the final
+      # ancestor. If there is no parent, then the children are relative to the
+      # parent.
       self$children <- find_children(ep, ancestor = parents[[1]])
     },
 
diff --git a/R/Lesson.R b/R/Lesson.R
index 2fbd220..9d5c5d6 100644
--- a/R/Lesson.R
+++ b/R/Lesson.R
@@ -2,10 +2,17 @@
 #'
 #' @description
 #' This is a wrapper for several [Episode] class objects.
+#' 
 #' @details
-#' Lessons are made of up several episodes within the `_episodes/` directory of
-#' a lesson. This class keeps track of several episodes and allows us to switch
-#' between RMarkdown and markdown episodes
+#' 
+#' This class contains and keeps track of relationships between [Episode]
+#' objects contained within [Carpentries
+#' Workbench](https://carpentries.github.io/workbench) and [Carpentries 
+#' styles](https://carpentries.github.io/lesson-example) lessons. 
+#'
+#' Read more about how to use this class in `vignette("intro-lesson", package =
+#' "pegboard")`
+#'
 #' @export
 Lesson <- R6::R6Class("Lesson",
   public = list(
diff --git a/man/Episode.Rd b/man/Episode.Rd
index 1839471..79340fc 100644
--- a/man/Episode.Rd
+++ b/man/Episode.Rd
@@ -7,8 +7,12 @@
 Wrapper around an xml document to manipulate and inspect Carpentries episodes
 }
 \details{
-This class is a fancy wrapper around the results of \code{\link[tinkr:to_xml]{tinkr::to_xml()}} and
-has method specific to the Carpentries episodes.
+The Episode class is a superclass of \code{\link[tinkr:yarn]{tinkr::yarn()}}, which transforms
+(commonmark-formatted) Markdown to XML and back again. The extension that
+the Episode class provides is support for both \href{https://pandoc.org}{Pandoc}
+and \href{https://kramdown.gettalong.org/}{kramdown} flavours of Markdown.
+
+Read more about this class in \verb{vignette("intro-episode", package = "pegboard)}.
 }
 \note{
 The current XLST spec for {tinkr} does not support kramdown, which
diff --git a/man/Lesson.Rd b/man/Lesson.Rd
index 29f422f..396fbbb 100644
--- a/man/Lesson.Rd
+++ b/man/Lesson.Rd
@@ -7,9 +7,10 @@
 This is a wrapper for several \link{Episode} class objects.
 }
 \details{
-Lessons are made of up several episodes within the \verb{_episodes/} directory of
-a lesson. This class keeps track of several episodes and allows us to switch
-between RMarkdown and markdown episodes
+This class contains and keeps track of relationships between \link{Episode}
+objects contained within \href{https://carpentries.github.io/workbench}{Carpentries Workbench} and \href{https://carpentries.github.io/lesson-example}{Carpentries styles} lessons.
+
+Read more about how to use this class in \code{vignette("intro-lesson", package = "pegboard")}
 }
 \examples{
 
diff --git a/vignettes/intro-lesson.Rmd b/vignettes/intro-lesson.Rmd
index ea08c64..b50b530 100644
--- a/vignettes/intro-lesson.Rmd
+++ b/vignettes/intro-lesson.Rmd
@@ -195,7 +195,8 @@ lapply(wb_lesson$built, class)
 ```
 
 You can use these to inspect how the content is rendered and see that the
-code blocks render what they should render:
+code blocks render what they should render. In thise case, `episodes/intro.Rmd`
+will render one output block and one image.
 
 ```{r summary-built}
 to_check <- c("page", "code", "output", "images", "warning", "error")