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

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

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