tomeshnet/p2p-internet-workshop

Integrate Remark presentations into the course website

Closed this issue · 7 comments

Shrinks99 commented

Remark presentations, all displayed in the browser in a similar fashion to how GitBook is used to display content presently. Once this is done all content should have been converted and GitBook should be fully removed as per #79.

benhylau commented

I suggest opening a PR soon from the remark-module-1 branch so we can get started on discussing where to place files. The new slides look great!

Shrinks99 commented

I'll open that as soon as it is integrated into the build script (something which I am unsure about the best way of doing myself).

Shrinks99 commented

@benhylau and I have discussed the benefits and drawbacks of in-browser Remark presentations VS a PDF for the slides. Here's what we have come up with. (This list will be kept up to date with more pros & cons as they come up).

HTML

Pros

  • Able to edit on the fly, even when workshop has been built
  • Suffers fewer rendering issues specifically related to Preview on Mac
  • Supports multi-media content

Cons

  • Requires more files included with the built package to work properly (fonts, JS, etc.)
  • Markdown must be written in-line in the HTML file (not located in a separate file)

PDF

Pros

  • Entire presentation wrapped up in a single file
  • Markdown can be located in a separate file for development
  • Can be easily distributed to students
  • Good for printing

Cons

  • Can suffer from crummy rendering in Preview for a second before it fixes itself
  • Presenters must run the build script when they want to make changes
  • You must be running a web-server to view changes in real time while editing the markdown

I am personally of the opinion that only one of these file types should be included as having two doesn't provide any actual benefit (that I can think of) to presenters. If PDF is dropped we no longer need to use Decktape and a large portion of the build script just involves moving things into place which is nice. That said, I like the simplicity of a single file being the only requirement for a presentation. I can't see a situation where presenters would have a strong preference between PDF or HTML although to be honest Remark in the browser is nice because it will always offer the same experience to presenters whereas PDFs are bound by whatever the viewer decides to do with them.

benhylau commented

Markdown must be written in-line in the HTML file (not located in a separate file)
Markdown can be located in a separate file for development

These are tooling issues that have nothing to do with HTML vs. PDF.

Presenters must run the build script when they want to make changes

This is very problematic as I have pointed out.

Other Pros of HTML over PDF:

  • Can support multimedia content if needed in the future
  • Assets can easily be individually downloaded and modified
  • Text reflows nicely

My preference, in order of priority:

  1. Have both, CI copies Remark to site and generates PDFs, so they are always in sync (I can imagine facilitator presenting with Remark and distributing PDF to students)
  2. Have Remark site only, all assets local of course
Shrinks99 commented

Distributing to students is an excellent use case and is convincing enough for me to want to include both formats. Perhaps the PDF can be located within the same folder that other PDF files are located in to make clear that presenters should be using Remark to give the talk and the PDF is there to distribute if they want to?

I don't think downloading and modifying assets on the fly is that huge of a deal, if you have time to open Illustrator and edit the SVG you probably have time to run the build script. This does however assume that people are building from source at all.

I'll set things up to support both.

benhylau commented

Perhaps the PDF can be located within the same folder that other PDF files

That was my expectation all along.

I don't think downloading and modifying assets on the fly is that huge of a deal

This is assuming people will fork the repo. In building the material itself, as I mentioned, I'd refresh about 100 times for a single module, I do not want to build PDF 100 times. Also at a conference I'd modify the content for the specific audience like in this one https://benhylau.github.io/talks-and-workshops/talks/201810_radical-networks/#1 it'd be really painful if I have to generate PDFs during the process.

Shrinks99 commented

This issue will be marked as resolved once remark presentations are integrated into the website build script.