R Package Documentation on the Web:

Zelig use case

Current Setup

Homepage

About/

Community/

Etc

Package docs

Current Setup: Workflow

Sphyinx

OpenScholar

I want to update the Homepage/About/etc . . .

I want to update the package docs . . .

Roxygen

Login

Click on widget to edit

Save

Login (GitHub)

Update RestructuredText

Commit

Jenkins build

Login (GitHub)

Update LaTeX

Build

Commit/Push to CRAN

Current Setup: Workflow

Sphyinx

OpenScholar

I want to update the Homepage/About/etc . . .

I want to update the package docs . . .

Roxygen

Login

Click on widget to edit

Save

Login (GitHub)

Update RestructuredText

Commit

Jenkins build

Login (GitHub)

Update LaTeX

Build

Commit/Push to CRAN

Remember to keep in Sync (links, css)

Issues

  • Lots of overlapping technologies
  • Source is in three places (2 GitHub repos + OpenScholar)
  • Reproducible code/previous versions spread over 2 repos, some not reproducible/version controlled
  • Difficult for external contributions

Issues

  • Lots of overlapping technologies
  • Source is in three places (2 GitHub repos + OpenScholar)
  • Reproducible code/previous versions spread over 2 repos, some not reproducible/version controlled
  • Difficult for external contributions

Causes

  • Large error surface -> more errors
  • Hard to find error
  • Hard to fix errors
  • Not practicing what we preach
  • Not a model for others

Ways Forward

1. Closest Analoge
2. Most Streamlined
3. Min OpenScholar 

4. Max OpenScholar 

Possibilities

Key Question

How should Open Scholar fit into a "best practices" software documentation workflow?

(Possible) Decision Criteria

  • User friendly
  • Reproducible
  • Version controlled
  • Minimise technology overlap
  • Syncing updates across platforms
  • Cost effective (open source first)
  • Persistant

Closest Analogue

OpenScholar

I want to update the Homepage/About/etc . . .

I want to update the package docs . . .

Roxygen + pkgdown

Login

Click on widget to edit

Save

Login (GitHub)

Update rmarkdown

Build

Commit/Push to CRAN

Remember to keep in Sync (links, css)

Remaining Issues

  • Fewer, overlapping technologies
  • Source is in two places (1 GitHub repo + OpenScholar)
  • Reproducible code/previous versions spread over 1 repo, some not reproducible/version controlled
  • Difficult for external contributions

Most Streamlined

I want to change/add anything

IQSSdevtools (Roxygen + pkgdown)

Login (GitHub)

Update rmarkdown

Build

Site hosted on package's GitHub repo in docs/ with IQSS URL

 

OpenScholar link via Dataverse

Push to GitHub/ CRAN/Dataverse

Benefits

  • Minimal number of technologies
  • Source is in one place
  • Reproducible code
  • Full version control
  • All docs stay in sync
  • Easy for external contributions (pull request of R markdown changes)
  • General solution to advocate

Min OpenScholar 

I want to change/add anything

Roxygen + osdown

Login (GitHub)

Update rmarkdown

Build

Push to GitHub/ CRAN/Dataverse

Site hosted on package's GitHub repo in docs/ with IQSS URL

 

OpenScholar link via Dataverse

Min OpenScholar

I want to change/add anything

Roxygen + osdown

Login (GitHub)

Update rmarkdown

Build

Push to GitHub/ CRAN/Dataverse

osdown [OpenScholar-down]:

a fork of pkgdown with Open Scholar branding/best practices

Benefits

  • Minimal number of technologies
  • Source is in one place
  • Reproducible code
  • Full version control
  • All docs stay in sync
  • Easy for external contributions (pull request of rmarkdown)
  • Promotes OpenScholar

Costs

R + web development resources needed to create osdown  

Max OpenScholar

I want to change/add anything

Roxygen

Login (GitHub)

Update rmarkdown

Build

New OpenScholar Capability: Open Scholar listens to GitHub for changes to HTML files and renders the result using OpenScholar templates.

Push to GitHub/ CRAN/Dataverse

Benefits

  • Small number of technologies for users
  • Content source is in one place
  • Reproducible content code
  • Full version control of content
  • All docs stay in sync
  • Easy for external contributions (pull request of rmarkdown)
  • Promotes Open Scholar

Costs

Potentially very resource intensive to setup and maintain

 

  • Is OpenScholar WYSIWYG possible?
  • If so, would require GitHub integration, becomes less general.

1. Closest Analoge
2. Most Streamlined
3. Min OpenScholar 

4. Max OpenScholar 

Possibilities

Made with Slides.com