[Discuss] Google Doc for describing best practices.

[Catarina Mota]

Hi all,

We're organizing a hackathon to arrive at some OSHW documentation best
practices and tools: http://www.opensourcewarehouse.org

It all started a few months ago with a few causal conversations with open
source hardware developers that were concerned with the fact that weren't
getting enough public contributions to their projects and also that they
sometimes found it difficult to build on top of other's projects. Both were
related to insufficient, deficient or hard to interpret documentation. So
this got us thinking about how can we improve documentation to make open
source hardware more accessible to all and to drive more contributions to
projects. This is the initial list of challenges we identified (to build
upon by the community):
http://www.opensourcewarehouse.org/problem-statement/

And here's an initial taxonomy (to be refined or abandoned at the
hackathon):
https://docs.google.com/spreadsheet/ccc?key=0AkNG-lv1ELQvdHViNEdtVHp4dHRWOU8tcDNSbXROY3c&usp=sharing

Since this a huge challenge and one that concerns the entire community, we
figured the best way to approach it would be to start with a hackathon to
identify the problems and find ways to tackle them.

We hope that some of the outcomes will be:

- A set of best practices for open source hardware documentation, including
a taxonomy and a check list.
- A set of recommended software tools for generating and sharing
documentation - this may either be the adoption of something that is
already out there or, more likely, a mashup of existing platforms
- A way to identify which parts of a project are open source and have
documentation
- The seed for an OSHW repository or a search engine

I hope many of you can join us and bring your ideas and insights to the
table. More details coming up on a separate email.

Cheers,
Catarina

On Tue, Mar 5, 2013 at 4:17 PM, Windell H. Oskay <windell at oskay.net> wrote:

>
> On Mar 3, 2013, at 5:35 PM, David A. Mellis <dam at mellis.org> wrote:
>
> > Hey all,
> >
> > I copied Nate's best practices document (
> http://www.oshwa.org/sharing-best-practices/) into a Google Doc:
> https://docs.google.com/document/d/1CiL9nd0xPOGRkHcNnOTZdHG-niAHteOm74f9PmAHdLg/edit?usp=sharing
> >
> > Please help improve it.
>
> I have made some significant edits to the document in a few sections:
> "Original Design Files," "Auxiliary Design Files," and some parts of
> "Additional Notes on Best Practice for OSHW" at the end.
>
> I hope that these edits are considered helpful.
>
>
> I still see a lot of room for improvement remaining, if anyone else would
> like to help out, in the following sections:
>
> * The intro to "Sharing Files"
> * Bill of materials
> * Software and Firmware -- could really be expanded a lot
> * Photos
> * Instructions
> * Legal practices to protect sharing
> * Distributing Hardware
> * Additional notes
>
>
>
> 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/
>
> _______________________________________________
> 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/20130307/f459a1da/attachment-0001.html>