[Discuss] Translation to Spanish for "Best Practices for Open-Source Hardware"

Sun Dec 15 14:39:40 UTC 2013

Hello,

Here's a first translation into English of the GitHub template for OSHW
projects that our community proposed:
https://github.com/dubsnipe/plantilla/.

For this, I basically translated Mario's template (
https://github.com/openhardwaresv/plantilla) into English with very minor
changes.

We'd love to hear your comments on what could be added, since we're really
interested in an efficient way to share and document projects by using an
already-existing tool. Perhaps a good way to test it out will be to jump
right in with a very basic project to see how it works. --Emilio

On 18 October 2013 09:08, Emilio Velis <rootsawalkin at gmail.com> wrote:

>
>
> ---------- Forwarded message ----------
> From: Emilio Velis <contacto at emiliovelis.com>
> Date: 18 October 2013 09:00
> Subject: Re: [Discuss] Translation to Spanish for "Best Practices for
> Open-Source Hardware"
> To: The Open Source Hardware Association Discussion List <
> discuss at lists.oshwa.org>
>
>
> Hi, Emilio here.
>
> Our idea behind creating a template for OSHW proyects has pretty much been
> explained by Mario. It's also worth throwing a couple more cents into the
> discussion:
>
> 1. All proyects, whether hardware or software, are in fact a combination
> of both. An open source software project can be pretty much explained of a
> code layer that interacts with a physical layer, and every project should
> be able to reflect all that in their code. A OSHW project is a codification
> of hardware specifications that usually interact with (or are developed by
> using) software, and the code has to reflect that in order to work.
>
> 2. Working with a code repository should be a good way to centralize the
> development of hardware projects. I remember trying to work as a volunteer
> at OSE a couple of years ago and I noticed that even finding the source
> code proved to be difficult at the OSE Wiki unless you're engaged and
> familiarized with platform and where things are (because let's admit it:
> that wiki is a bit of a mess). Some people sometimes just want to find the
> core development files to create their work, and then they will read the
> documentation to sort out any problems during fabrication, and not the
> other way around.
>
> It's not that we're not interested in a platform to develop a community,
> but we're also interested in finding an efficient way to 'force' developers
> into creating digitalized, structured and standarized specifications of
> their work. It does require a change in the mindset of developers, but we
> think it's worth the trouble. Software projects are very into forums and
> wikis, but the core of development is done in platforms such as GitHub.
> Think of it as the school library: a place without noise, where people come
> because they already know what they want to do before coming in.
>
> With so much discussion around, it feels like we'll end up writing a paper
> on "Distribution Challenges of Complex Open Hardware Projects". Just
> saying. --Emilio.
>
>
>
> On 18 October 2013 08:20, J. Simmons <jrs at mach30.org> wrote:
>
>> Good day Antoine,
>>
>> This is J. Simmons, president and founder of Mach 30. I agree with your
>> sentiment about wanting to know Mach 30's position with respect to OSHW and
>> how that affects the service provided by ODE. And in truth, you are
>> probably correct that for most people only time will tell.
>>
>> However, I believe with a little bit of digging into Mach 30's past
>> activities you will see we have already demonstrated a clear commitment to
>> OSHW and ODE is a vendor neutral project hosting platform.
>>
>> First, Mach 30 is a US public charity (501c3) -
>> http://mach30.org/about/public-records/tax-exempt-status-documentation-and-process/.
>> This status and corporate structure forbids  our board from earning a
>> profit from any and all Mach 30 activities, including the operation of ODE.
>>
>> Second, part of our IRS approved nonprofit mission is to support the OSHW
>> community. We have decided our key activities in this mission area are
>> operating ODE so any OSHW project can have free project hosting, and openly
>> publishing export control policies so all OSHW developers can confidently
>> share designs without fear of breaking laws related to ITAR and other
>> export controls - http://mach30.org/ectf/
>>
>> Finally, ODE is itself open source software, and users can always choose
>> to move from our hosted service to their own installation -
>> https://opendesignengine.net/projects/ode. Granted, some of the docs are
>> a little out of date, but we are about to begin another round of updates to
>> ODE and documentation is one of the items we will be addressing during
>> those updates.
>>
>> I hope some of that helps to demonstrate our position is open and
>> neutral.
>>
>> Yours,
>>
>>  -J
>>
>> Sent from my iPhone
>>
>> On Oct 18, 2013, at 7:55, FREE SMALL WIND TURBINE PROJECT PEOPLE <
>> smallwindturbineproj.contactor at gmail.com> wrote:
>>
>> Hi Matt,
>> Sure, any fun-and-easy to use highly reliable collaborative platform,
>> would be very helpful for any FLOSHW project. We approve.
>> We've just a piece of possible comment concerning mach30: how should any
>> neophyte people evaluate the neutral position of march30 comparing to
>> famous strongly neutral platform used for software - ie for example
>> something like savannah ?
>> That's a question we still have difficulty to answer with certainty.
>> Maybe it's just a question of time of existence ... we don't know.
>> Thanks for your sharing,
>> Very interesting discussion indeed.
>> Freely
>> Antoine
>>
>>
>> 2013/10/17 Matt Maier <blueback09 at gmail.com>
>>
>>>
>>>
>>> On Thu, Oct 17, 2013 at 11:24 AM, Mario Gómez <mxgxw.alpha at gmail.com>wrote:
>>>
>>>>  Hi Matt! Thanks for sharing!
>>>>
>>>> It seems very complete tool, definitly we must try it! It would be
>>>> really helpful for doing project management. I'm going to suggest it to
>>>> Emilio.
>>>>
>>>> However one of things that I personally like about distributed
>>>> versioning systems like git and using a "simple" template is that you don't
>>>> depend on a system or platform to share and collaborate. I mean, if GitHub
>>>> goes belly up tomorrow you still can work, collaborate and share your
>>>> changes latter by other means.
>>>>
>>>
>>>  Well, like most things in life there isn't one best way to do
>>> something, there are just tradeoffs. A simple template is great if the
>>> project is easy for the participants to understand. That's a function of
>>> the objective complexity of the project and the ability of the participants
>>> to deal with it. Even something as seamingly simple as a chair can grow
>>> into a complex project (AtFAB<http://www.treehugger.com/eco-friendly-furniture/atfab-launches-flatpack-furniture-made-through-networked-distributed-manufacturing.html>).
>>> And even when you have an entire customer service department dedicated to
>>> creating extensive, validated instructions for assmbling a chair, there
>>> will still be people who don't understand (IKEA furniture<http://www.washingtonpost.com/blogs/compost/wp/2013/08/16/some-assembly-required-the-lies-of-ikea-and-beyond/>).
>>> In an open source project, the core developers are capable of handling a
>>> lot more complexity than the casual tourists. You can have a simple
>>> repository, where you just dump all the files, and a core developer can
>>> figure out what each file does and how to use them; but because the
>>> repository has no structure ONLY the core developers can understand the
>>> project. The more structured the files are, the lower the barriers to
>>> entry, and the more people can participate.
>>>
>>> It's the same documentation challenge as always. A repository with a lot
>>> of structure is self-documenting, but it does increase the overhead which
>>> does take some time away from pure development. At the beginning that might
>>> seem like an inefficient use of resources because the only participants are
>>> a few core developers, who don't need a "complex" repository. But in the
>>> future, when the project wants to attract more participants and scale up,
>>> the "complex" repository is what will allow new people to understand the
>>> project enough to join it.
>>>
>>> That's particularly important for hardware projects because they require
>>> inherently more investment than software projects. Someone can try to run a
>>> program, see that it doesn't work correctly, and move on with their life.
>>> But actually building a piece of hardware, only to THEN find out that it
>>> doesn't work correctly, is a much larger cost. Participating in a hardware
>>> project is a larger risk, so there is more value to investing in a
>>> "complex" repository to ensure the project is easy to understand.
>>>
>>> Therefore, it makes sense to use more infrastructure-dependent services,
>>> even though that increases the risk that the project could suffer from the
>>> service disappearing in the future.
>>>
>>>
>>>
>>>>  The idea of having just a simple template is that everything is
>>>> inside the repository. I mean, the repository it's not a part of the
>>>> project like in ODE and other project management tools but the whole
>>>> project itself is tracked by the repository.
>>>>
>>>> May be it's because my programming background, but for me, at the end,
>>>> OSHW is just source code that helps you to replicate physical things. So I
>>>> don't understand why in most cases we like to keep design files,
>>>> documentation, and everything outside the repository. For me every
>>>> different piece in the project is just "another kind" of source code, even
>>>> the documentation is just the source code that is going to be used for
>>>> compiling ideas on own people's minds.
>>>>
>>>
>>>
>>> I totally agree with that metaphor :) but I think it's the need for a
>>> human mind to do the "compile" step that results in hardware projects being
>>> fragmented. When the whole project is digital (software) it's possible to
>>> automate everything. The human can just make some selections, then sit back
>>> and let the computer do everything. Not all projects are like that, but it
>>> is at least a possibility for all software projects. Hardware, however,
>>> does not have that option. A human needs to be able to access and
>>> manipulate the digital files in a way that THEIR brain understands; it
>>> can't be automated.
>>>
>>> Also, again, hardware not only costs more, it requires more costly
>>> tools. So people tend to get one toolchain working and want to stick with
>>> that since standing up another toolchain would require a significant
>>> investment. It's a lot harder to be sure that people are understanding and
>>> working-with hardware in identical ways than it is to be sure they're using
>>> software identically.
>>>
>>> Since hardware costs more, and hardware tools cost more, that means that
>>> changes and alternatives cost more. The core team might build a great
>>> project using Metric parts. Then new members create a version using
>>> Imperial parts. If the core team introduces a change to the design do they
>>> need to test it in Metric AND Imperial? Maybe, but odds are they won't.
>>> Implementing the change in Imperial will be left up to the people who want
>>> to use Imperial, but it doesn't really justify splitting off into an
>>> entirely separate project. Still, there might be unforseen complexities in
>>> the conversion, like there not being room for a slightly different fastener
>>> size, or the editing tools making it difficult to shift holes in the
>>> necessary way. That means the Imperial team will have to do some
>>> development work of their own. If they're sharing a "simple" repository
>>> with the Metric version they will quickly confuse what used to be a simple
>>> project (like with crazy long file names and new README instructions). So
>>> instead they'll make their own little respository somewhere else, just for
>>> the work they need to do for the conversion.
>>>
>>> And that's just one example off of the top of my head. Hardware projects
>>> frequently justify working in different locations because changes and
>>> alternatives require different tools, and different people, which cannot be
>>> replicated by all participants.
>>>
>>> A "complex" repository can provide organized space for those different
>>> people/tools. That way they can work in a "different" place while still
>>> working in the same place.
>>>
>>>
>>>>
>>>> I would say that we can easily treat the template just as a basic
>>>> building block, that fills the most basic needs and doesn't need any
>>>> external tool to be useful by itself, and then you can share it over any
>>>> tool that you preefer or feel more comfortable, this could be ODE, GitHub,
>>>> Thingiverse, etc.
>>>>
>>>
>>>
>>> That will work right up until the project attracts new people. It's a
>>> perfectly serviceable approach as long as the project won't change in the
>>> future. If the project does change, then the just-a-template approach will
>>> quickly require more documentation re-work than it's worth. At that point
>>> the project will splinter and without a united community the project will
>>> die...or limp along under the supervision of one or two people taking it in
>>> different directions.
>>>
>>> Here's an example (Distributed Collaboration<http://opensourceecology.org/wiki/Distributed_Collaboration>).
>>> I wrote the first (only?) instructions for replicating the LifeTrac for
>>> Open Source Ecology. What I mean by that is I wrote the instructions three
>>> times. Each time I had to basically start over again because the
>>> just-a-template approach can't accomodate any significant changes in the
>>> project, let alone in how the project is explained.
>>>
>>> It's attractive at the beginning because developers hate documentation.
>>> It allows the developers to technically have open sourced their project.
>>> But it pretty much guarantees that new people can't actually utilize the
>>> project's files, so it strains the spirit of open source.
>>>
>>> If the project is worth open sourcing, then it's worth investing a
>>> little bit extra in infrastructure at the beginning so that the project
>>> (particularly a hardware project) has some hope of scaling in the future.
>>>
>>>
>>>>
>>>> Regards,
>>>> Mario.
>>>>
>>>> P.D.: I really like this list, I hope when the forum/wiki/etc is ready
>>>> we could continue having this interesting talks.
>>>>
>>>>
>>>>
>>>>  On Thu, Oct 17, 2013 at 8:27 AM, Matt Maier <blueback09 at gmail.com>wrote:
>>>>
>>>>>
>>>>>  On Wed, Oct 16, 2013 at 8:45 PM, Mario Gómez <mxgxw.alpha at gmail.com>wrote:
>>>>>
>>>>>>    I would say both.
>>>>>>
>>>>>> Personally I always liked the idea of software repositories like PyPI
>>>>>> (https://pypi.python.org/pypi). Websites like Thingiverse, and
>>>>>> Upverter are great but are more on focused on the design files than the
>>>>>> whole picture of the OSHW.
>>>>>>
>>>>>
>>>>> Mario,
>>>>>
>>>>> Before you build your own solution you should check out Mach 30's Open
>>>>> Design Engine (ODE). https://opendesignengine.net/
>>>>>
>>>>> It was built from the ground up as a hardware-specific project
>>>>> management tool (Mach 30 wants to build open source rockets and
>>>>> satellites). You can add whatever you want for your specific project, like
>>>>> a wiki, and/or a forum, and/or a blog, and/or a repository, etc. You can
>>>>> then fill up that project with all of your files and everyone can come to
>>>>> one place to coordinate themselves. You can even fork the entire project
>>>>> and the new project gets everything that was in the original, files, the
>>>>> whole forum, all the comments, etc and the new project can go in its own
>>>>> direction from that baseline.
>>>>>
>>>>> Here is J. Simmons, the founder of Mach 30, explaining how to use ODE
>>>>> for an example robot project.
>>>>> http://www.youtube.com/watch?v=COH4E_Ie1P0
>>>>>
>>>>> _______________________________________________
>>>>> discuss mailing list
>>>>> discuss at lists.oshwa.org
>>>>> http://lists.oshwa.org/listinfo/discuss
>>>>>
>>>>>
>>>>
>>>> _______________________________________________
>>>> discuss mailing list
>>>> discuss at lists.oshwa.org
>>>> http://lists.oshwa.org/listinfo/discuss
>>>>
>>>>
>>>
>>> _______________________________________________
>>> discuss mailing list
>>> discuss at lists.oshwa.org
>>> http://lists.oshwa.org/listinfo/discuss
>>>
>>>
>>
>> _______________________________________________
>> discuss mailing list
>> discuss at lists.oshwa.org
>> http://lists.oshwa.org/listinfo/discuss
>>
>>
>
>
>
> --
> "Jack of all trades, master of none, though often better than a master of
> one."
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.oshwa.org/pipermail/discuss/attachments/20131215/d3e14c1c/attachment-0001.html>