Merge pull request #74 from jhelvy/jph-docs

Lots of updates to the docs

DESCRIPTION

@@ -22,7 +22,7 @@ License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
 VignetteBuilder: knitr
 Depends:
     R (>= 4.0.0)

README.Rmd

@@ -15,56 +15,35 @@ knitr::opts_chunk$set(
 )
 ```
 
-# surveydown <a href='https://jhelvy.github.io/surveydown/'><img src='man/figures/logo.png' align="right" style="height:139px;"/></a>
+# surveydown <a href='https://jhelvy.github.io/surveydown/'><img src='man/figures/logo.png' align="right" style="width: 120px;" alt="surveydown package logo: a hex shape with a large letter S and a down arrow"/></a>
 
 ### Markdown-Based Surveys With [Quarto Shiny Documents](https://quarto.org/docs/dashboards/interactivity/shiny-r.html).
 
-> Note: This is still a very early-stage project and not quite production ready, though we're happy if you'd like to try it out and give us feedback!
+> Note: This is still a very early-stage project. We don't yet recommend using it for collecting data, but we would love any feedback you have if you try it out!
+
+This project brings together three open source technologies ([Quarto](https://quarto.org/), [shiny](https://shiny.posit.co/), and [supabase](https://supabase.com/)) to create dynamic, markdown-based surveys. Here's the basic concept:
 
 <br>
 <center>
-<img src='man/figures/technologies.png' align="center" style="max-height:200px;"/>
+<img src='man/figures/technologies.png' align="center" style="max-height:180px;" alt="image showing the three technologies used in the surveydown platform along with their logos: quarto (for designing surveys), shiny (for rendering the survey), and supabase (for storing data)"/>
 </center>
 <br>
 
-This project brings together three open source technologies ([Quarto](https://quarto.org/), [shiny](https://shiny.posit.co/), and [supabase](https://supabase.com/)) to create dynamic, markdown-based surveys. Here's the basic concept:
-
 1. Design your survey as a [Quarto shiny document](https://quarto.org/docs/dashboards/interactivity/shiny-r.html) using markdown and R code.
 2. Render your doc into a [shiny](https://shiny.posit.co/) app that can be hosted online and sent to respondents.
 3. Store your survey responses in a [supabase](https://supabase.com/) database.
 
-The {surveydown} R package works in tandem with our [surveydown Quarto extension](https://github.com/jhelvy/surveydown-ext) to make everything work. After installing the package, we recommend working from one of our template example surveys to design your own.
+The {surveydown} R package works in tandem with our [surveydown Quarto extension](https://github.com/jhelvy/surveydown-ext) to make everything work. 
 
-**See the [documentation page](https://jhelvy.github.io/surveydown/) to get started making your own surveydown survey!**
+**See the [documentation](https://jhelvy.github.io/surveydown/articles/surveydown.html) to get started making your own surveydown survey!**
 
 # Background & Motivation
 
-`surveydown` was created as a markdown-based alternative to platforms like Google Forms, Qualtrics, Survey Monkey, etc. Unlike every other platform, it allows the user to define their entire survey content using markdown and R code, making the survey itself fully reproducible and easy to share and collaborate with others. The resulting shiny app for each survey can be hosted on a number of platforms, like [shinyapps.io](https://shinyapps.io/) or [huggingface](https://huggingface.co/), and the survey data collected is owned by the survey designer in their supabase account. Best of all, everything is open source and free :)
-
-If you're curious where this whole idea came from, check out this [blog post](https://www.jhelvy.com/blog/2023-04-06-markdown-surveys/), which outlines more on the general idea and the motivation for it. The post is now outdated in terms of the overall design, but it provides something of an origin story and some of the motivation for developing this project.
-
-# Quick Start
+Most survey platforms (e.g., Google forms, Qualtrics, etc.) use drag-and-drop interfaces to design surveys, making version control and collaboration with others difficult. They're also not reproducible. 
 
-Install the {surveydown} **R package** (not available on CRAN yet):
+As an open-source, markdown-based platform, surveydown was designed to address these problems. In surveydown, all survey content is created with plain text (markdown and R code) in a single .qmd file that renders into a shiny app. This makes your survey easy to reproduce, share, and version control with common tools like Git. The resulting shiny app for each survey can be hosted on a number of platforms, like [shinyapps.io](https://shinyapps.io/) or [huggingface](https://huggingface.co/), and the survey data collected is owned by the survey designer in a supabase account. Best of all, everything is open source and free :)
 
-```{r}
-#| eval: false
- 
-# install.packages("remotes")
-remotes::install_github("jhelvy/surveydown")
-```
-
-To start with an **example survey** (which includes the extension), run:
-
-```{r}
-#| eval: false
-
-# To install the survey under your current path
-surveydown::sd_create_survey()
-
-# To designate a path inside your current path
-surveydown::sd_create_survey("path/to/folder")
-```
+If you're curious where this whole idea came from, check out this [blog post](https://www.jhelvy.com/blog/2023-04-06-markdown-surveys/), which outlines more on the general idea and the motivation for it. The post is now outdated in terms of the overall design, but it provides something of an origin story and some of the motivation for developing this project.
 
 # TODO List
 

README.md

@@ -1,26 +1,26 @@
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
-# surveydown <a href='https://jhelvy.github.io/surveydown/'><img src='man/figures/logo.png' align="right" style="height:139px;"/></a>
+# surveydown <a href='https://jhelvy.github.io/surveydown/'><img src='man/figures/logo.png' align="right" style="width: 120px;" alt="surveydown package logo: a hex shape with a large letter S and a down arrow"/></a>
 
 ### Markdown-Based Surveys With [Quarto Shiny Documents](https://quarto.org/docs/dashboards/interactivity/shiny-r.html).
 
-> Note: This is still a very early-stage project and not quite
-> production ready, though we’re happy if you’d like to try it out and
-> give us feedback!
+> Note: This is still a very early-stage project. We don’t yet recommend
+> using it for collecting data, but we would love any feedback you have
+> if you try it out!
+
+This project brings together three open source technologies
+([Quarto](https://quarto.org/), [shiny](https://shiny.posit.co/), and
+[supabase](https://supabase.com/)) to create dynamic, markdown-based
+surveys. Here’s the basic concept:
 
 <br>
 <center>
-<img src='man/figures/technologies.png' align="center" style="max-height:200px;"/>
+<img src='man/figures/technologies.png' align="center" style="max-height:180px;" alt="image showing the three technologies used in the surveydown platform along with their logos: quarto (for designing surveys), shiny (for rendering the survey), and supabase (for storing data)"/>
 </center>
 
 <br>
 
-This project brings together three open source technologies
-([Quarto](https://quarto.org/), [shiny](https://shiny.posit.co/), and
-[supabase](https://supabase.com/)) to create dynamic, markdown-based
-surveys. Here’s the basic concept:
-
 1.  Design your survey as a [Quarto shiny
     document](https://quarto.org/docs/dashboards/interactivity/shiny-r.html)
     using markdown and R code.
@@ -31,23 +31,27 @@ surveys. Here’s the basic concept:
 
 The {surveydown} R package works in tandem with our [surveydown Quarto
 extension](https://github.com/jhelvy/surveydown-ext) to make everything
-work. After installing the package, we recommend working from one of our
-template example surveys to design your own.
+work.
 
-**See the [documentation page](https://jhelvy.github.io/surveydown/) to
-get started making your own surveydown survey!**
+**See the
+[documentation](https://jhelvy.github.io/surveydown/articles/surveydown.html)
+to get started making your own surveydown survey!**
 
 # Background & Motivation
 
-`surveydown` was created as a markdown-based alternative to platforms
-like Google Forms, Qualtrics, Survey Monkey, etc. Unlike every other
-platform, it allows the user to define their entire survey content using
-markdown and R code, making the survey itself fully reproducible and
-easy to share and collaborate with others. The resulting shiny app for
+Most survey platforms (e.g., Google forms, Qualtrics, etc.) use
+drag-and-drop interfaces to design surveys, making version control and
+collaboration with others difficult. They’re also not reproducible.
+
+As an open-source, markdown-based platform, surveydown was designed to
+address these problems. In surveydown, all survey content is created
+with plain text (markdown and R code) in a single .qmd file that renders
+into a shiny app. This makes your survey easy to reproduce, share, and
+version control with common tools like Git. The resulting shiny app for
 each survey can be hosted on a number of platforms, like
 [shinyapps.io](https://shinyapps.io/) or
 [huggingface](https://huggingface.co/), and the survey data collected is
-owned by the survey designer in their supabase account. Best of all,
+owned by the survey designer in a supabase account. Best of all,
 everything is open source and free :)
 
 If you’re curious where this whole idea came from, check out this [blog
@@ -57,25 +61,6 @@ now outdated in terms of the overall design, but it provides something
 of an origin story and some of the motivation for developing this
 project.
 
-# Quick Start
-
-Install the {surveydown} **R package** (not available on CRAN yet):
-
-``` r
-# install.packages("remotes")
-remotes::install_github("jhelvy/surveydown")
-```
-
-To start with an **example survey** (which includes the extension), run:
-
-``` r
-# To install the survey under your current path
-surveydown::sd_create_survey()
-
-# To designate a path inside your current path
-surveydown::sd_create_survey("path/to/folder")
-```
-
 # TODO List
 
 This is a running list of things we’re working on adding to the project:

pkgdown/_pkgdown.yml

@@ -1,50 +1,36 @@
 url: https://jhelvy.github.io/surveydown/
 
 home:
-  title: Package title
-  description: Package description
+  title: Build markdown-based surveys with quarto shiny documents
 
 template:
-  params:
-    bootswatch: cosmo
+  bootstrap: 5
+  light-switch: true
+  bslib:
+    primary: "#0054AD"
+    border-radius: 0.5rem
+    btn-border-radius: 0.25rem
+    danger: "#A6081A"
   opengraph:
     image:
       src: https://jhelvy.github.io/surveydown/reference/figures/logo.png
       alt: "Logo for the surveydown package"
 
-navbar:
-  title: "surveydown"
-  left:
-    - icon: fa-home fa-lg
-      href: index.html
-    - text: "Functions"
-      href: reference/index.html
-    - text: "Usage Guide"
-      menu:
-        - text: "1. Quick Start"
-          href: articles/quick_start.html
-        - text: "2. Installation"
-          href: articles/installation.html
-        - text: "3. Editing Survey"
-          menu:
-            - text: "3.1 Overview"
-              href: articles/overview.html
-            - text: "3.2 Question Types"
-              href: articles/question_types.html
-            - text: "3.3 Question Formatting"
-              href: articles/question_formatting.html
-        - text: "4. Control Logic"
-          href: articles/control_logic.html
-        - text: "5. Database Setup"
-          href: articles/database_setup.html
-        - text: "6. Deployment"
-          href: articles/deployment.html
-    - text: "Changelog"
-      href: news/index.html
+articles:
+- title: surveydown
+  navbar: ~
+  contents:
+  - install
+  - content
+  - questions
+  - formatting
+  - control
+  - database
+  - deploy
 
 reference:
-- title: "Survey Setup"
-  desc: "Functions for setting up and creating surveys"
+- title: Survey Setup
+- subtitle: Functions for setting up and creating surveys
   contents:
   - sd_setup
   - sd_create_survey