Platform for Community + Documentation

The Problem Sep 2018

Getting good documentation is slow and error-prone with the current constraints:

• bottleneck: Marcin has nearly all the knowledge
• translation: fellows must translate Marcin's knowledge
• documentation formation: requires 4 people: 1writer,1photographer,1Marcin,1loose-ends
• quality feedback loop: does not exist -- how do you know if it's good?

And other issues:

• time-consuming to link a Table of Contents (could be auto-generated w/ markdown)
• google slides doesn't translate to HTML

Additionally, there's no onboarding process where there's a feedback loop. This leads to a lot of repetition. Rather than asking a question once, it gets asked, potentially, hundreds or thousands of times. This needs to never happen.

Proposed Solution (Alex)

The core pain point is lacking a quality feedback loop. If you have this plus in-person events, you can actually hire someone or give people a free experience if they do the documentation *especially if the core steps are already in place and what's needed are touch-ups and clarifications*.

Here's what I propose:

• Use Discourse, an open-source forum, to capture questions
• Sync w/ an app so fellows get messages on their phone and can address them
• Make questions easy to find by being adjacent to manual in HTML

 * Scope questions by module and step #
 * Open questions specifically to: feelings, ideas, technical, cross-talk
 * Tag questions by novice / standard / advanced

• During initial documentation, use audio-to-text tech to write instead of typing

By always making it so people can ask questions, we can know when there needs to be different versions when we suddenly make a change and forget to document it. This is also significantly improves the documentation and therefore ppl's xp with building a 3d printer+.

Next Steps (Alex)

• showcase basic flow from markdown to discussion-ready feedback loop
• put discourse and html-based manual on same page
• document flow for publishing to wordpress
• document flow for readers to post questions
• document flow for editors to check-off & answer questions
• translate existing google slides to markdown
• test the following:

   [x] collaboration works w/ 2 collaborators
   * document doesn't "jump" w/ multiple collaborators
   * publishes to pdf in a smooth way? (is there a new page mechanism?)
   * can you create various templates w/ word character limits & img locations? (you can in StackEdit but not sure about HackMD)
   * auto-make a table of contents

• Use HackMD.io as a collaboration tool. It has these benefits:

 * easy image upload (just paste, and auto-hosts on imgur)
 * collaboration works
 * has book and slides view
 * has granular permissions per file
 * you can embed using an iframe
 * you can embed youtube, vimeo, gists, slideshare, pdfs
 * you can style ALERTS (really useful for us -- green, blue, yellow, red)
 * you can do footnotes

Other Options That were considered

• md2gslides -- but needs significant additions to make useable
• StackEdit -- best option re: features minus one, collaboration doesn't work intuitively. this is a deal-breaker.