Platform for Community + Documentation - Revision history

Alexau: /* Next Steps (Alex) */

2018-09-23T14:33:16Z

Next Steps (Alex)

← Older revision		Revision as of 14:33, 23 September 2018
Line 40:		Line 40:
	* auto-make a table of contents		* auto-make a table of contents

	* Use HackMD.~~com~~ as a collaboration tool. It has these benefits:		* Use HackMD.io as a collaboration tool. It has these benefits:
	* easy image upload (just paste, and auto-hosts on imgur)		* easy image upload (just paste, and auto-hosts on imgur)
	* collaboration works		* collaboration works

Alexau: /* Next Steps (Alex) */

2018-09-22T23:06:02Z

Next Steps (Alex)

← Older revision		Revision as of 23:06, 22 September 2018
Line 27:		Line 27:

	= Next Steps (Alex) =		= Next Steps (Alex) =
	* showcase basic flow from markdown to ~~google slides~~		* showcase basic flow from markdown to discussion-ready feedback loop
	* add discourse
	* put discourse and html-based manual on same page		* put discourse and html-based manual on same page
	* document flow for publishing to wordpress		* document flow for publishing to wordpress

Alexau: /* Next Steps (Alex) */

2018-09-22T23:05:02Z

Next Steps (Alex)

← Older revision		Revision as of 23:05, 22 September 2018
Line 42:		Line 42:

	* Use HackMD.com as a collaboration tool. It has these benefits:		* Use HackMD.com 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 ==		== Other Options That were considered ==
	* md2gslides -- but needs significant additions to make useable		* 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.		* StackEdit -- best option re: features minus one, collaboration doesn't work intuitively. this is a deal-breaker.

Alexau: /* Next Steps (Alex */

2018-09-22T23:00:34Z

Next Steps (Alex

← Older revision		Revision as of 23:00, 22 September 2018
Line 26:		Line 26:
	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+.		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 =		= Next Steps (Alex) =
			* showcase basic flow from markdown to google slides
			* add discourse
			* 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.com as a collaboration tool. It has these benefits:

			== 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.

Alexau at 22:47, 22 September 2018

2018-09-22T22:47:39Z

← Older revision		Revision as of 22:47, 22 September 2018
Line 25:		Line 25:

	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+.		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 =

Alexau: /* Proposed Solution (Alex) */

2018-09-22T22:47:19Z

Proposed Solution (Alex)

← Older revision		Revision as of 22:47, 22 September 2018
Line 24:		Line 24:
	* During initial documentation, use audio-to-text tech to write instead of typing		* 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.		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+.

Alexau: /* The Problem Sep 2018 */

2018-09-22T22:33:48Z

The Problem Sep 2018

← Older revision		Revision as of 22:33, 22 September 2018
Line 9:		Line 9:
	* time-consuming to link a Table of Contents (could be auto-generated w/ markdown)		* time-consuming to link a Table of Contents (could be auto-generated w/ markdown)
	* google slides doesn't translate to HTML		* 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) =		= Proposed Solution (Alex) =

Alexau: Created page with "= The Problem Sep 2018 = Getting good documentation is slow and error-prone with the current constraints: * bottleneck: Marcin has nearly all the knowledge * translation: fell..."

2018-09-22T22:32:10Z

Created page with "= The Problem Sep 2018 = Getting good documentation is slow and error-prone with the current constraints: * bottleneck: Marcin has nearly all the knowledge * translation: fell..."

New page

= 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

= 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.