Distributed Collaboration

The internet has created a brand new opportunity for people separated by distance, but united by goals, to work together. The "distributed collaboration" idea has a strong element of assumed volunteerism in it. Professionals, united by a fiduciary responsibility (and the hierarchy that implies), don't need any help. It is the people who want to help a worthy cause in their spare time that need help.

Volunteers, by definition, are nearly universally unable to produce good work on a regular schedule. They tend to work when they can, or when they feel like it, so they need a system that isn't broken by newbies making mistakes or old-timers disappearing suddenly.

The following process attempts to achieve that goal. Each step is well defined and really only a small part of the process depends on a core team of employees. The rest of the process is a way for volunteers to expand a small piece of crucial work into a diverse array of useful tools.

I developed this process while working on the LifeTrac fabrication instructions. So, since that is the only example of the full process, I'll use it as an illustration.

=Benefits=
 * This process clearly defines which steps are necessary and who is responsible for them.
 * The entire process is transparent and easy to understand.
 * Feedback mechanisms are built into the structure.
 * Any number of alternative definitions, projects and reports can exist side-by-side.
 * Every step which can practically be done over the internet has a method for doing that.
 * Each step is flexible enough to allow people to come and go as necessary without crippling the process.

=Lessons Learned=
 * The definitions > project > report process would be straight-forward to automate. The key is the "self-evident" steps. When the machine is broken down into little units, each one is simple enough to understand on its own. As long as you accomplish each individual step, you will eventually end up with a complete machine. Changes are compartmentalized so they only affect one or a few discrete steps.
 * Definitions should be created in a content library. People would upload working files, like CAD. Then, images and dimensions would be pulled out of those working files and uploaded with a descriptive title.
 * Projects should be created in whatever program works best and then that becomes a working file.
 * Reports should be compiled only after the machine has reached a point of stability. Also, there should be some sort of standardized format so that they're easy to read and important information isn't left out.
 * The entire process could be incorporated into a single tool. Or, at worst, a single workflow tool that guides the use of different tools. Each definition becomes at least on step, and each step becomes at least one line in the report. Along the way each definition/step can accumulate comments that are incorporated into the final report.

=Concepts=
 * Self-evident
 * Something meets this standard when the way the thing is described requires no additional information. It is the smallest indivisible unit of a machine.
 * In practice, this goal is achieved when a part or step is so simple that a mere title or illustration is sufficient to fabricate or execute it.
 * For example: a picture of part A and part B held together with matching bolt holes lined up with a title like "bolt together" is self-evident. It requires no additional explanation. On the other hand, a picture of a fully assembled machine would not be self-evident. Additionally, a picture of the bolt first going through part A, then through part B, would probably be unnecessary.
 * This standard is not objective; it requires a bit of an intuitive touch...or a lot of feedback. The distributed collaboration process is designed to maximize feedback so that intuition is unnecessary.

=Definitions= Each machine is designed and prototyped by one person or, at most, a small team.

The prototypers "define" the machine. They generate descriptions, sketches, illustrations, CAD, models, etc. Technically, as long as they record everything coherently an experienced fabricator could figure out how to reproduce the machine. This is the bare minimum necessary. Without this material the prototype machine might as well have never been built.

Prototypers have three responsibilities in this distributed collaboration process:

1) They must define the machine in discrete steps, each of which is simple enough to be "self-evident."

2) They must post their definitions in a way that is publicly accessible and coherently organized.

3) They must remain available for, and responsive to, requests for additional or rephrased definitions.

LifeTrac Example
[[Media:Frame outer base measurements.jpg]] This is an image created by taking a screen capture of the LifeTrac 3 CAD file. It was imported into Open Office and labels were added. The result is an illustration that should be mostly self-evident. Any details not included in the illustration would be added as an introduction to a related group of illustrations or as a caption. [[Media:LifeTrac 3 definitions.odt]] This is a table created by taking a lot of those illustrations, putting them in a list, then adding headings and explanations. In Open Office, if you use the styles & formatting menu to assign "heading 1" to some text, that text can be automatically incorporated into an index, making the large document easier to navigate.

It turns out there are a lot of man-hours involved in this stuff. Since I was working on my own, I used my hard drive as a content library. There is no reason an online file library couldn't be used instead.

=Projects= Each machine is documented by remote volunteers (or anyone).

The documenters create "projects" based on the definitions. They generate a database that contains the steps, resources and time-frame necessary to replicate the machine. This is a powerful augmentation to the definitions. With this material replicators have all the information they need to start immediately and proceed without any surprises.

Documenters have three responsibilities in this distributed collaboration process:

1) They must refer directly to the machine definitions in a way that is "self-evident."

2) They must seek out, clarify and record all the information relevant to fabricating the machine.

3) They must work in a standardized, shared format without keeping any relevant information to themselves.

At the moment, project management software is the preferred tool for building the projects. It is a database that already has a GUI and reports. There are plenty of free, open-source project management programs available online. OpenProj was used to test the distributed collaboration process and functioned adequately.

How To Do It
1) Find the machine definitions. If they aren't broken up into self-evident parts then have a way to do that or ask the prototyper to do it.

2) Isolate one part.

3) Create one or more steps to shape the part.
 * First, create a "resource" in the PM software. The name of the resource should be the dimensions of the cut piece of stock material. For example, <4" x 4" x 1/4" by 3' angle> could be a resource name. Additionally, create a resource for any tools necessary to accomplish the step. For example, could be a resource name.
 * Second, create a "step" in the PM software. The name of the step should be the action necessary to shape the material. For example,  could be a step name.
 * Third, assign the resource(s) to the step. Additionally, assign any tools necessary. Now the complete entry could be read .
 * Fourth, create any other steps necessary to shape the part. If holes are necessary, you could create . The best thing to do is refer to a definition image that shows the correct hole locations, their dimensions, and how to locate them on the part.
 * NOTE: create a different resource for every individual piece that uses different overall dimensions. It is not necessary to make two entries for parts that are both <4" x 4" x 1/4" by 3' angle>. It is necessary to make two separate entries for a parts that are <4" x 4" x 1/4" by 3' angle> and <4" x 4" x 1/4" by 4' angle>. This will ensure that the BOM is both complete and intuitive. You don't know how the replicator is going to want to obtain the correct amount of raw material. Providing them with exactly the outside dimensions of all the parts allows them the most flexibility in sourcing. For example, if there are 12 square tubes of various lengths, all under 8 feet, do not list <12 x 8' square tube> in the BOM. That is misleading. Instead, list <2 x 8'> and <4 x 7.5'> and <6 x 6.75'> so the replicator can figure out for themselves how to combine the parts to minimize waste or maximize efficiency or whatever.

LifeTrac Example
[[Media:OSE LifeTrac Fabrication.pod]] This is the LifeTrac OpenProj file. You can download OpenProj for free here. OpenProj on Sourceforge

After the definitions exist, they can be used as references for project steps. The frame member example you saw higher up on the page could be broken into two steps. The first step would be "cut to length" and would be assigned resources. This is where I tracked tools and materials for the Bill of Materials (more on that later). If you assign the piece of stock material necessary then the program tracks it for you. The second step could be "drill holes" and would also be assigned resources. In this case it's stuff like drill bits of the appropriate size. This makes it really easy to build up a list of the stuff you'll need because you can capture the information right when you're thinking about it and it's tracked forever. [[Media:Lifetrac steps in openproj.jpg]] here is a screen capture of the program so you can see what I mean.

The best part is that when someone wants to actually replicate the LifeTrac they can use the project file to organize their work. For example, by tracking what they do, and in what order, and how long it takes them, and any extra resources they needed, they can edit the file into a perfect record of what they did (or will do, if they did that ahead of time). Then they can send a copy of their file back to the documenters and prototypers so they get exactly the feedback they need to improve the machine and the documentation.

=Reports= Each machine is published by remote volunteers (or anyone).

The publishers create "reports" based on the projects. They generate a finished document that presents the information in the project and definitions in a professional, authoritative manner. This step is necessary to open up machine replication to as many people as possible. With this material replicators have a universally accepted tool for communicating their endeavor to team members, investors and interested parties.

Publishers have three responsibilities in this distributed collaboration process:

1) They must refer directly to the machine project and definitions in a way that is "self-evident."

2) They must communicate to as broad an audience as possible, without ambiguity, bias or omission.

3) They must grant the world permission to obtain, utilize, copy and distribute the report freely.

LifeTrac Example
[[Media:LifeTrac Fabrication Report 25FEB2012.pdf]] This is a report that was generated from the project file and definitions detailed previously. Open Office was used to create several files, which were incorporated into a master document. The master document was then exported as a pdf. There are a few formatting issues, but the entire report is pretty much just a really long table, so that keeps things clearly organized.

=Using the OSE Wiki= The wikis is a good place to capture the fast-moving stuff.

1) Create a definition file. When possible, it should be a CAD file in a universal format. However, CAD files aren't the easiest things in the world to work with, and they are not an ideal way to communicate information. So, upload the CAD file for the developers, but turn the CAD file into a series of jpegs and add important labels (like dimensions and units). It is the jpegs that will become the definitions that other people can intuitively turn into projects and then into reports. Give each jpeg a strong file name. Try to include a word or two describing which subsystem it is a part of, a name for the part that makes it distinct from all other parts, and a word to discriminate this file from all other images of the same exact part. It is good to upload a jpeg that is just a picture of the piece itself, then a second jpeg that has dimensions written over it. That way people can work with the raw illustration when you (and the hard drive you stored it on) aren't available. For example, one of the LifeTrac parts is the "cant rail" so the name of the file that illustrates where to drill the holes is "frame cant rail measurements."

2) Log in to the wiki.

3) Select "Upload file" from the "Toolbox" menu on the left side of the screen.

4) Click "choose file" and navigate to the file on your hard drive.

5) Click "upload file"

6) When the screen changes, confirm that you uploaded the correct file. Then click in the URL address bar at the top of your browser and highlight the filename. It will be everything that follows "opensourceecology.org/wiki/File:". Copy the filename to the clip board.

7) In another tab (or window) navigate to the page where you are going to post the definition.

8) In the appropriate section, type " image: < /gallery>" except you can put each word on a different line and don't include those spaces after the carrots.

9) Paste the file name after the "image:" word.

10) If there are more definitions (which there probably will be) then create a new line with "image:" between the "gallery" tags and past the new file name. Rinse and repeat.

=Credentials= Matt_Maier

I graduated from the Air Force Academy with a degree in Systems Engineering Management. Now I work as a satellite ground system engineer.

=References= "The data of the GVCS truly constitutes its value, and as such cannot be trusted to a single, centralized source. An additional hurdle is the disconnected, intermittent and limited (DIL) connectivity of some users of the global SoS."

"A distributed version control system could assist tremendously in decentralizing the GVCS workflow, as well as protect the critical data assets of the GVCS global knowledge store through distributed duplication...Making distributed version control more user-friendly represents a significant task in its own right." - N Bollweg, A System of Systems Analysis of the Global Village Construction Set