P:Documentation Standards::Iterative Documentation Flow - Revision history

Alexau: /* First Pass Documentation: How to do it */

2018-10-24T22:43:13Z

First Pass Documentation: How to do it

← Older revision		Revision as of 22:43, 24 October 2018
Line 34:		Line 34:

	Here's an [https://docs.google.com/presentation/d/1B00v35UQNA2RSCtFoKCz8qJgdLHulmJaafer9WIkz1k/edit?usp=sharing example].		Here's an [https://docs.google.com/presentation/d/1B00v35UQNA2RSCtFoKCz8qJgdLHulmJaafer9WIkz1k/edit?usp=sharing example].

	~~== Video Instruction ==~~
	~~Here's a short video of Alex filling out the first pass documentation.~~

	= Team-ready documentation: How to do it =		= Team-ready documentation: How to do it =

Alexau: /* Instruction: How to do Public-ready documentation */

2018-10-24T22:42:36Z

Instruction: How to do Public-ready documentation

← Older revision		Revision as of 22:42, 24 October 2018
Line 53:		Line 53:
	See the [https://wiki.opensourceecology.org/wiki/3D_Printer_Manual 3D Printer Manual] for an example.		See the [https://wiki.opensourceecology.org/wiki/3D_Printer_Manual 3D Printer Manual] for an example.

	= ~~Instruction~~: How to do ~~Public~~-~~ready documentation~~ =		= Public-ready Documentation: How to do it =
			Add themes to your build phases for novice hardware builders and create another Q&A doc with sections with each build phase.

			See [https://docs.google.com/presentation/d/1rUhTMleIRipqhow2xcj9W2i2JxVswxyEp-P3yOgWDPg/edit#slide=id.g454d00b924_0_0 3D Printer Quality Control Lists] for an example.

			During a public workshop, insist that all participants only ask questions to instructors. Train participants to reference the Q&A before asking a question. Instructors document all questions and answers.

	=Links=		=Links=
	This page is based on [[Documentation Standards]]		This page is based on [[Documentation Standards]]

Alexau: /* Instruction: How to do Workshop-ready documentation */

2018-10-24T22:36:10Z

Instruction: How to do Workshop-ready documentation

← Older revision		Revision as of 22:36, 24 October 2018
Line 48:		Line 48:
	* '''During the replication, write for your teammate''' so that they understand what you've written.		* '''During the replication, write for your teammate''' so that they understand what you've written.

	= ~~Instruction: How to do~~ Workshop-ready documentation =		= Workshop-ready documentation: how to do it =
	Before you give your first workshop, take the team-ready documentation and have it fit the [https://docs.google.com/presentation/d/1wxU4fahWuoyCOdc7zsgX8Hur-aZWGca0Q5tuBizlHt8/edit#slide=id.p Template: 6 layer documentation].		Before you give your first workshop, take the team-ready documentation and have it fit the [https://docs.google.com/presentation/d/1wxU4fahWuoyCOdc7zsgX8Hur-aZWGca0Q5tuBizlHt8/edit#slide=id.p Template: 6 layer documentation].

Alexau: /* Instruction: How to do Workshop-ready documentation */

2018-10-24T22:34:58Z

Instruction: How to do Workshop-ready documentation

← Older revision		Revision as of 22:34, 24 October 2018
Line 48:		Line 48:
	* '''During the replication, write for your teammate''' so that they understand what you've written.		* '''During the replication, write for your teammate''' so that they understand what you've written.

	= Instruction: How to do Workshop-ready documentation =		= Instruction: How to do Workshop-ready documentation =
			Before you give your first workshop, take the team-ready documentation and have it fit the [https://docs.google.com/presentation/d/1wxU4fahWuoyCOdc7zsgX8Hur-aZWGca0Q5tuBizlHt8/edit#slide=id.p Template: 6 layer documentation].

			See the [https://wiki.opensourceecology.org/wiki/3D_Printer_Manual 3D Printer Manual] for an example.

	= Instruction: How to do Public-ready documentation =		= Instruction: How to do Public-ready documentation =

Alexau: /* Orientation: Key things to keep in mind. */

2018-10-24T22:32:51Z

Orientation: Key things to keep in mind.

← Older revision		Revision as of 22:32, 24 October 2018
Line 44:		Line 44:

	== Orientation: Key things to keep in mind. ==		== Orientation: Key things to keep in mind. ==
	* When creating a build phase, try to minimize the number of quality control approvals. This creates unnecessary work. If 2 items both needs checking, but can be independently built, then it's better to check them both at the same time and put them in the same build phase, rather than create 2 build phases.		* When creating a build phase, try to '''minimize the number of quality control approvals.''' This creates unnecessary work. If 2 items both needs checking, but can be independently built, then it's better to check them both at the same time and put them in the same build phase, rather than create 2 build phases.
	* Before the replication, write for speed so that it makes sense to you.		* '''Before the replication, write for speed''' so that it makes sense to you.
	* During the replication, write for your teammate so that they understand what you've written.		* '''During the replication, write for your teammate''' so that they understand what you've written.

	= Instruction: How to do Workshop-ready documentation =		= Instruction: How to do Workshop-ready documentation =

Alexau: /* Team-ready documentation: How to do it */

2018-10-24T22:32:19Z

Team-ready documentation: How to do it

← Older revision		Revision as of 22:32, 24 October 2018
Line 42:		Line 42:

	See here for [https://docs.google.com/presentation/d/1Tf0Y6vfeLYfOFRYqfkhiGxdcJScQYFUfivibrd4t1G4/edit#slide=id.p Template: Team-ready Documentation]		See here for [https://docs.google.com/presentation/d/1Tf0Y6vfeLYfOFRYqfkhiGxdcJScQYFUfivibrd4t1G4/edit#slide=id.p Template: Team-ready Documentation]

			== Orientation: Key things to keep in mind. ==
			* When creating a build phase, try to minimize the number of quality control approvals. This creates unnecessary work. If 2 items both needs checking, but can be independently built, then it's better to check them both at the same time and put them in the same build phase, rather than create 2 build phases.
			* Before the replication, write for speed so that it makes sense to you.
			* During the replication, write for your teammate so that they understand what you've written.

	= Instruction: How to do Workshop-ready documentation =		= Instruction: How to do Workshop-ready documentation =

Alexau: /* Instruction: How to do Team-ready documentation */

2018-10-24T22:29:16Z

Instruction: How to do Team-ready documentation

← Older revision		Revision as of 22:29, 24 October 2018
Line 38:		Line 38:
	Here's a short video of Alex filling out the first pass documentation.		Here's a short video of Alex filling out the first pass documentation.

	= ~~Instruction~~: How to do Team-ready documentation =		= Team-ready documentation: How to do it =
			Team-ready documentation occurs in preparation for and during the first replication of a prototype.

			See here for [https://docs.google.com/presentation/d/1Tf0Y6vfeLYfOFRYqfkhiGxdcJScQYFUfivibrd4t1G4/edit#slide=id.p Template: Team-ready Documentation]

	= Instruction: How to do Workshop-ready documentation =		= Instruction: How to do Workshop-ready documentation =

Alexau: /* Orientation: Key things to keep in mind. */

2018-10-24T21:49:33Z

Orientation: Key things to keep in mind.

← Older revision		Revision as of 21:49, 24 October 2018
Line 22:		Line 22:

	== Orientation: Key things to keep in mind. ==		== Orientation: Key things to keep in mind. ==
	As a project steward, the purpose of first pass documentation is to ~~help guide another team member in documenting the work that you're doing, when you assist them in also doing the work at a later time. Because you will be there~~ to improve the documentation later~~, the point here is just~~ to get a skeleton ~~down that can help orient future documenters~~. Therefore:		As a project steward, the purpose of first pass documentation is to record enough info to improve the documentation later on. Aim to get a skeleton. Therefore:

	* '''Don't spend a lot of time documenting''' the work, aim for under 5-7 minutes for every 55 minutes of work.		* '''Don't spend a lot of time documenting''' the work, aim for under 5-7 minutes for every 55 minutes of work.

Alexau: /* Instruction: How to do First Pass documentation */

2018-10-24T21:48:07Z

Instruction: How to do First Pass documentation

← Older revision		Revision as of 21:48, 24 October 2018
Line 16:		Line 16:
	# '''Public-ready''' - This starts as being the same as a workshop-ready manual. It is improved when during workshops, instructors log and answer participant questions until the documentation is comprehensive and matches the documentation standards.		# '''Public-ready''' - This starts as being the same as a workshop-ready manual. It is improved when during workshops, instructors log and answer participant questions until the documentation is comprehensive and matches the documentation standards.

	= ~~Instruction~~: How to do ~~First Pass documentation~~ =		= First Pass Documentation: How to do it =
	First pass documentation significantly increases the ease of documenting your work in the future.		First pass documentation significantly increases the ease of documenting your work in the future.

Alexau: /* Overview: Phases of Documentation */

2018-10-24T21:47:06Z

Overview: Phases of Documentation

← Older revision		Revision as of 21:47, 24 October 2018
Line 9:		Line 9:

	= Overview: Phases of Documentation =		= Overview: Phases of Documentation =
	There are 4 phases of documentation: first pass, team-ready, workshop-ready, and public-ready. See below for actual instructions to complete each phase ~~of the documentation, including templates and videos~~.		There are 4 phases of documentation: first pass, team-ready, workshop-ready, and public-ready. See below for brief overview of these 4 phases followed by the next section with actual instructions to complete each phase.

	# '''First Pass''' - This is just a bare bones description of steps you followed to do the work.		# '''First Pass''' - This is just a bare bones description of steps you followed to do the work.