[Discuss] discuss Digest, Vol 10, Issue 101

Matt Maier blueback09 at gmail.com
Wed Apr 10 16:48:07 UTC 2013


Those are great examples of how hard it is to make hardware documentation

Software can be remixable because designing and implementing it happens
entirely in the cyber domain. Hardware documentation crosses between the
cyber and physical domains.

The critical details of a software project are all just logic, so anyone
with enough time and intelligence can figure them out. The critical details
of a hardware project often involve un-digitizable things like "finger
tight." Sometimes the knowledge for an important detail is literally stored
in the unconscious processes of the craftsman. Like they know when to turn
down the speed on a drill because of how it smells or sounds or the way it
vibrates their arm.

Explaining that to someone else is impossible. If they haven't actually
done it long enough in the real world no amount of thinking about it will
be enough.

If you do find a way to explain that kind of stuff, or make it unnecessary,
then it's still really easy to forget to mention a critical detail because
it simply didn't occur to you that it might be important. Like if the
project was created by someone who happened to have an extremely clean
workspace that didn't contaminate a process, but for everyone else the
process tends to fail randomly from contamination.

Even when you can digitize all of the important dimensions, because the
physical domain is so much more complicated it might still be impossible to
follow even a perfect set of instructions. If a process needs low humidity,
and you're trying to replicated it in the tropics, then you're SOL.


On Wed, Apr 10, 2013 at 10:03 AM, Pierce Nichols
<pierce at logos-electro.com>wrote:

> The biggest lack I see in using Github for hardware is the fact that
> is lacks well-integrated diff and merge tools for hardware. Windell
> posted some decent hacks for doing this, but they're not integrated
> into the workflow and that's the problem most in need of solution.
> There's also a more serious issue, which is how much trickier it is to
> instantiate a hardware design as compared to compiling source. Beyond
> the brute physical labor of building the thing, there are substantial
> hidden process parameters that are not readily discoverable. These can
> range from relatively obvious things like the builder's skill in
> various processes and the quality of their equipment to subtle things
> like the way a part is clamped in a fixture or the temperature at
> which it is dried after cleaning.
> There is a good reason aerospace folks have a gigantic stick up their
> collective ass about process control and being able to trace the
> origins of all parts. You don't always know what's really important
> about a process, and if you don't control the production process, you
> are likely to get bitten.
> -p
> On Tue, Mar 26, 2013 at 5:30 PM, Matt Maier <blueback09 at gmail.com> wrote:
> >
> > Windell, this was your question from another message, but I'm gonna
> paste it
> > here so it's more relevant.
> >
> > "Can you please explain, what it is exactly about the complexity of
> hardware
> > projects that you think Github cannot handle?"
> >
> >>
> >> This is actually one of the big improvements in Eagle 6-- the XML file
> >> format.  Some other EDA programs (including gEDA and KiCAD) have
> >> human-readable, diffable file formats.
> >>
> >>
> >> Also, github does support visual diffs for images in repositories.  One
> of
> >> the consequences of this is that if you include a current image of the
> >> SCH/BRD with each commit, you can use the visual diff even on pure
> binary
> >> files.
> >> ( I've written more about this kind of stuff on my blog, too:
> >>
> http://www.evilmadscientist.com/2011/improving-open-source-hardware-visual-diffs/
> >> )
> >>
> >>
> >> Windell H. Oskay, Ph.D.
> >> Co-Founder and Chief Scientist
> >> Evil Mad Scientist Laboratories
> >> 175 San Lazaro Ave, STE 150
> >> Sunnyvale CA 94086
> >> http://www.evilmadscientist.com/
> >>
> >>
> > I am not trying to imply that there is anything wrong with Github. It's a
> > specific example mostly because "Github for hardware" is a popular phrase
> > that more-or-less captures the issue. Github is basically the gold
> standard
> > (in several combined dimensions) for open source software collaboration,
> so
> > it makes sense to want the same benefits for hardware.
> >
> > Git as a software engine provides distributed version control, which is
> > awesome and seems like a turn-key solution for ANY files, no matter what
> > they describe. Github as a web portal provides additional capabilities
> that
> > augment Git and those are where I think it falls short of what open
> hardware
> > requires.
> >
> > By that setup I do not mean that it's impossible to do open hardware
> > development with the current tools. Obviously, it's possible.
> >
> > What I mean is what I assume Chris Anderson meant when he wrote, "until
> your
> > project is in a public version-control system, it’s open source in name
> > only." A project that releases all of the source files under an open
> license
> > is an open project, but it is open in name only. To be actively open it
> has
> > to attract new developers and inspire activity like forking, generational
> > change, and interconnected dependencies.
> >
> > The (open and/or free) tools available at the moment, including the ones
> on
> > Github, are not up to the task of tracking all of the interrelated
> > dimensions of a hardware project well enough to allow an "actively open"
> > level of activity. When we remix the digital elements of a hardware
> project
> > we are not messing around with the project itself; we are merely
> adjusting a
> > description of the project. It is much simpler to specify an absolutely
> > correct transition between one bit of code and another than it is to
> specify
> > an absolutely correct transition from one physical object or process to
> > another. It is much easier to introduce ambiguity into hardware
> definitions
> > and much harder to fight off entropy because there are so many more
> things
> > that can be inadequately or improperly described.
> >
> > Up to this point it has only been worthwhile to tackle that level of
> > complexity when a project could plausibly become a marketable commercial
> > product. The tools to do it absolutely exist, but they are absolutely
> only
> > worth the cost and learning curve when a bunch of jobs are on the line.
> This
> > is analogous to the inception of the RepRap project. Dr. Bowyer didn't
> > invent 3D printers, he just made a 3D printer that cost so little, and
> was
> > so easy to use, it covered the lowest conceivable part of the market. We
> > aren't going to invent any aspect of product lifecycle management, but we
> > are trying to invent a tool that is so cheap and easy to use that it
> covers
> > the bottom of the market. One hobbyist working in their spare time on a
> pet
> > project.
> >
> > I believe that Github (and version control in general) can handle
> hardware
> > projects if the information is structured in the correct way and has the
> > right user interface. That structure/interface is what we need to work
> out.
> >
> > By way of a supporting example, I'd like to direct your attention to the
> > LifeTrac Fabrication instructions over at Open Source Ecology. I know
> those
> > instructions are pretty good because I wrote them. But, for the same
> reason,
> > I also know that they are dead. The label "open" can be un-sarcastically
> > applied to them, but there is no way for developers to interact with
> them.
> > They are open in name only. Halfway through producing the unpublished
> > version of those instructions I started over because I realized that the
> > information needed to be recorded in a way that allowed interaction. At
> the
> > time the best option I could think of was an open source project
> management
> > program (a database with a user interface). The majority of those
> > instructions were actually generated from an OpenProj file, as described
> > here. That is better because if someone wants to modify the tractor
> (modify
> > the build instructions) they can edit the OpenProj file, which will keep
> > track of resources and steps automatically (more-or-less). Then they can
> > generate a new set of instructions without having to rewrite all of the
> > details by hand. Better, but all that increase in capability does is
> > highlight how much MORE capability is necessary to make the project truly
> > remixable. No one can read or edit the actual OpenProj file without the
> > software. No part of the file or the result can be pulled out and
> combined
> > with anything else. It is a cathedral with a common room, not a bazaar.
> >
> > The point I got to in that documentation project is roughly the point the
> > whole open hardware community is currently at. Sure, I could put the
> > LifeTrac's OpenProj file on Github, but there's no relevant way to
> compare
> > differences between two database files. The problem is not with the
> > documentation so much as it's with the structure it has been captured in
> and
> > the tools necessary to interact with that structure.
> >
> > To sum up: hardware projects are more complicated because more variables
> > have to be accounted for if the instructions are to be correct. It is
> > currently possible to capture that complexity and to store it on Github,
> but
> > it is not possible to interact with it in a way that allows for the
> project
> > to be "truly" open.
> >
> > Cheers,
> > Matt
> >
> > _______________________________________________
> > discuss mailing list
> > discuss at lists.oshwa.org
> > http://lists.oshwa.org/listinfo/discuss
> >
> --
> Pierce Nichols
> Principal Engineer
> Logos Electromechanical, LLC
> _______________________________________________
> discuss mailing list
> discuss at lists.oshwa.org
> http://lists.oshwa.org/listinfo/discuss
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.oshwa.org/pipermail/discuss/attachments/20130410/14ee4501/attachment-0001.html>

More information about the discuss mailing list