Open Source Ecology Forums

Marcin

We are following the Instructionals Template - http://openfarmtech.org/wiki/Instructional_Page_Template - for documentation. The goal is to make the build replicable by individuals with either manual tools or with access to the tools of digital fabrication, such as a CNC torch table or an industrial robotic arm. The first Full Product Release is the Compressed Earth Brick press, so this can become our model case for producing quality documentation. The materials to build on for the documentation are the corresponding material on the blog (Full Product Release, open source CEB press, compressed earth block press), wiki (3 prototypes listed, CEB Press category), and design repository.

Howard_V_Agnew

I do not know if anyone has attempted to put this document together. In the absence of knowing, I am right now attempting to draft it using OpenOffice 3.3.0 (Build 9567). I hope to complete a draft, or if I cannot because I find a gap of needed materials, at least I will be able to identify specific areas I need to inquire about. Whether I am able to complete a document draft or not, I intend to post my working OpenOffice file so that others may review and even fix and re-upload an edited version. If I do complete a draft, I will post a .PDF export (which, unless someone tells me otherwise, is the preferred format).

Howard_V_Agnew

Some notes/comments while working on this draft ...

First, I've copied the GNU Free Documentation License, Version 1.3 into the copyright page for the document and assigned its copyright to "Open Source Ecology." I hope this is okay ... since this document will/should be a collaboration, I think it would be silly to "copyright" it to one particular author, certainly not me! I created a "Document Development History" page after the Copyright page to log edits into the document (date, description ['First Draft' for this one I am working on], Name and Contact E-mail address for the collaborating author making the edit. Feel free to change this.

I'm encountering some glitches attempting to collate the data into one OpenOffice document. First, a slight conundrum -- should I attempt to incorporate the Google Documents as a live data source into the document from, say, the bill of materials? I've decided against that for now, and to simply paste in the most recent source at the time of the draft because:

As I compose this draft, I am copying some information in the actual text and instructions, doing some editing work on it and the like. If the instructions and Bill of Materials change, if I have live data sources, they will no longer match the machine construction instructions (since the machine construction instructions will be static text, not updated as live updates). I presume the Bill of Materials would only be updated with matching changes in the construction instructions, and the OpenOffice document will need to be manually updated anyway (at which time the Bill of Materials can be manually updated).
I cannot assume that the person printing the instructions has constant Internet Access and may print their document while not having had Internet access for some time. I think it would be safer for them to have a complete, static document.

I believe we will likely have multiple iterations of a document, even between CEB design changes, with everything from typographical and grammatical edits to instructional or data error fixes. I have learned to thus organize files I make, such as word processing documents, by including the date of edit in the filename. It may be important to archive and retain older document versions, especially when a new version is made because of CEB design changes, and re-saving under a new file name incorporating a date or "document build number" (I find it easier to do the former, adding a letter if needbe if I happen to make several edits in one day) makes it easy to keep around the older document versions. For instance, for this initial draft, I am naming the file "Compressed Earth Brick Press - Building Instructions - 2011-09-18.odt"

Howard_V_Agnew

I forgot to mention the second glitch! OpenOffice doesn't properly handle the '-lead fields on the Bill of Material. They are supposed to tell the spreadsheet to leave the numbers alone, essentially treat them as text, not try to, say, convert 1/8 to 0.125. The ' itself isn't supposed to display, but for some reason the Google Documents-to-Open Office conversion causes the ' to display in OpenOffice.

I'm manually fixing this before pasting the Bill of Material over. The 1/4, 1/2 and 3/4 fraction characters that are auto-corrected when typing in those fractions look nice, but aren't consistent since there are no other fraction characters for 1/8, 3/8, etc. I have pondered using Insert Object > Formula > Fraction, but besides being a time-consuming hassle (it can take a good 20-30 seconds to create each fraction ... by itself, this wouldn't be a problem except for the other problem) but it doesn't work well; OpenOffice doesn't treat the fraction object as a character, so you can't nicely write a fraction like 3/8 and nicely fit " after to properly indicate inches. It also consumes about one and a half line-heights of vertical space, leading to uneven row heights in the spreadsheet if some rows have no fractions while others do.

It is one feature I do miss from Microsoft Office, as I seem to recall they had some better-looking options for making fractions.

For now, until a finalized standard for displaying fractions is determined by the Documentation group, I'm going to stick with letting AutoCorrect do its thing and the rest of the fractions will be simple x/y text. As said, I am fixing the Google to Open Office conversion glitches as I see them.

Howard_V_Agnew

Safety information is missing (http://opensourceecology.org/wiki/CEB_Press/Manufacturing_Instructions/Safety) ... this is definitely not something I would feel good about trying to guess at from afar, nor can I sign off on a draft as being ready to publish until we have this information in the instructions. Someone at FeF should take a paranoid look at the machine and determine the hazards for building and operating the machine. Remember that these instructions will be for anyone to build, so don't leave out anything because of "duh, no one would do X."

Just hazarding some thoughts (pardon the pun):

What safety equipment will be needed in the build (should go right in with the list of tools and bill of materials)? Goggles/safety glasses, gloves, safety boots?
Safety in using the equipment
Safety in handling the material (safe lifting techniques, especially important trying to handle large blocks)
Could the machine, in normal operation or a malfunction, eject rocks or other material that could hit someone?
Is it possible a person's jewelry, clothing, fingers or feet could get grabbed by any part of moving machinery?
Is it advisable to always operate the machine with a buddy to watch out for safety?
In an emergency, is there an easily found and accessed kill switch?
Could a worst case scenario malfunction cause a fire, electrical short capable of electrocuting someone or explosion? Expert designers of the machine should be aware of any possible sources of heat or sparks (moving parts frictioning one another, electrical shorts in the control circuits, etc.) I am not very knowledgeable, just guessing at some of this.

As I find more things that are missing and preventing this from becoming a complete machine construction instruction document, I will continue to point them out.

Howard_V_Agnew

I've found two different lists of tools to build the CEB: http://opensourceecology.org/wiki/CEB_Press/Manufacturing_Instructions/Tools and http://opensourceecology.org/wiki/CEB_Press/Bill_of_Materials#Tools_and_Supplies ... at least the latter includes some safety equipment.

I suggest the two tools lists get consolidated into one, or people trying to change/update/fix the wiki instructions may be confused as to which one to update (and may not know about the other one).

Bastelmike

@Howard

I can't see the problem You have with those two different lists. Keeping them separated makes sense.

List No 1 (tools) lists all the tools, You must have at hand when building a CEB press. The bill of materials is standard in listing all materials and off-the-shelf components for one CEB press!

How can You mix them up??? If you want to build ten CEB presses, You have to buy all parts in BOM 10 times. But You won't have to buy 10 welders !!!!

Mike

mjn

> I will post a .PDF export

That's fine. We can always figure out a different format later, if needed.

> should I attempt to incorporate the Google Documents as a live data source into the document from, say, the bill of materials?

I agree with the choice make the BOM static rather than linking live to the Google Doc Spreadsheet.

BTW, if you want to track updates to the OSE Wiki, have a look at http://opensourceecology.org/wiki/Special:RecentChanges - this will tell you what gets changed. Thus, if the CEB BOM changes, you'll know about it.

> I cannot assume that the person printing the instructions has constant
Internet Access and may print their document while not having had
Internet access for some time.

While that is true, they are going to be severely disadvantaged building any of the GVCS without it. Still, a printable manual seems like a good idea to me.

> The 1/4, 1/2 and 3/4 fraction characters

If I were doing this, I'd use "1/2" rather than attempt a fraction character or equation. Yeah, not as pretty, but at least it will stay in-line and remain editable.

> Safety information is missing

Stub out the section and leave it blank. Alternatively, you can put in sub-sections likely to be required. Safety considerations have never been a priority in OSE development, unfortunately.

----

One final comment on this project you've taken on. Have you discussed this with Marcin? Without his blessing, any work you do on this is likely to be ignored. I'd hate to see you do a lot of work only to have it be thrown away. You are making assumptions about the collaborative nature of OSE work which may not be true.

- Mark

Howard_V_Agnew

I have not contacted anyone except for David Ihnen, who has become their construction manager (he's in a couple videos talking about the FeF site development). Its my understanding Marcin's time and focus is well spent on the prototyping, and I thought instead of sitting on my thumbs, this could be a good opportunity to see if I have what is needed to help as a technical writer, by doing what I can to get the documentation going with what information has been posted about how to build one of the already prototyped machines. I was going to wait until I had the documentation as ready I could make it. If they have started the documentation in-house without updating this thread, its only my time I've wasted then, and -- unfortunately -- I have time in plenty of abundance (but no money to enjoy or even much share it).

If my work proves to be for naught because they're already developing one, well, all I will have wasted is time. I have chatted with David Ihnen about it, as he know each other IRL and I have been friends for awhile (unfortunately I don't yet know anyone else personally with the project), and he's encouraged me to go for it.

I am a bit stuck having found some contradictory and redundant information (such as the tools needed to do the job; I've found two different lists on the wiki, each of which has some things the other list doesn't). Its been suggested that I should try to reconcile the lists, which I will probably do to remove the obstacle and help organize the wiki, and suggest one or the other get archived so there would be only one working copy for the those actually at FeF trying to put out instructions to worry about updating.

Howard_V_Agnew

Persuant to your last comment, Mark, I have now sent an e-mail to Marcin asking if my efforts are merely duplicating something already underway at FeF. I have noticed a lot of re-organization activity on the wiki. However, I don't see the harm aside from potentially wasting my own time in trying to chisel away at the documentation until I hear otherwise. Thank you for the constructive remark!

Howard_V_Agnew

Apologies for spamming this thread so much with little updates now and then, but thought it might be helpful, its certainly getting some tasty useful constructive tidbits as I proceed bit by bit.

I was going to proceed in order and wait to complete a draft of each section before proceeding, clear out the hurdles one by one, but I think I will proceed forward while waiting on some information I requested about the CEB Bill of Materials spreadsheet on Google Documents. I am not sure, but I believe the maintainer is William Neal, as he added the spreadsheet embeds into the CEB Press/Bill of Materials wiki article. Marcin seems to have posted a Bill of Material modification under one of the spreadsheet embeds in the wiki article. I made a note to William on his wiki user talk page (not sure what the best method is for contacting specific folk) to see if he might update it (I don't believe I have access to update it ... I could download, try to figure out how to add in the change, upload and change the wiki article to reflect it, but that would take a lot more time and could cause some issues if William was unaware the spreadsheet he made [if he even made it?] was changed). It seems a bit simpler to simply proceed past this for now, let William make the change to the spreadsheet, and I'll simply need to remember to update the table in the word processing document when the source Google Documents spreadsheet is updated. Marcin's change to the Bill of Material may reflect (or, if not, perhaps necessitate) a corresponding change within the construction instructions themselves anyway.

Also, there seems to be two variants of the CEB Press described in the Google Documents spreadsheet: a normal version and a "super" version (which I guess makes bigger blocks/bricks). For now, just trying to establish a working document prototype/template, I think I will just worry for the regular version. I am undecided, anyway, whether the "super" version should have its own separate construction instruction document (that's rather clumsy, errk ... we should find or come up with a better term, if someone hasn't already, especially distinctive terms for the technical documentation of building the machines to distinguish word processing versions such as I am working on, the wiki articles and other formats).

Howard_V_Agnew

New ponderance: Undoubtedly these documents will become sizable. As with any technical documentation, they need to ultimately be sculpted into clear, concise and simple step by step instructions with diagrams. I am wondering, though, if we should include Research & Development information found in the machine wiki articles, a page with each instruction describing Open Source Ecology and the overall GVCS, and the particular machine's specific role in it or if that would be too flowery and extraneous for the intended purpose of simple (if lengthy) instructions to actually build the specific machine.

For now, I think I will skip the research and development information, but I think I will stick in a page or so describing the OSE and overall GVCS. I'll probably just copy and paste such info from the wiki for now, see how it works with the overall document.

Howard_V_Agnew

Also, as a note, I realize it is probably slowing my progress even further, but I am prolifically adding comments (with the Open Office document marking/commenting feature) to the .ODT as I go. I mark the exact URL from the spreadsheets, wiki articles, etc. that I refer to or copy from, and note specific weaknesses I have or find and placeholders that must be filled in before the document is ready to release. I hope the inserted comments will be useful, when the draft is at a point I am ready to post it for collaborative revising/editing. I do not know when that will be, but the Bill of Materials-esque lists and tables will need serious improvement before I am ready to post the first draft. I did post a blurb I wrote for the document; I stuck it in its own thread so comments/critiques/suggestions specific to it can be organized under that thread.

Howard_V_Agnew

Marcin e-mailed me back (does that guy ever sleep!?) and pointed me to Brianna. I've e-mailed her, and will essentially halt direct work on the .ODT itself until I hear back from her.

I think there's a lot of useful related "side" work I can do on the wiki, as when I finally got to the actual meat of the manufacturing instructions, I found inconsistencies in the source material on the wiki (for the very first part). I noted in detail the problem I saw on the talk page for the article at http://opensourceecology.org/wiki/Talk:CEB_Press/Manufacturing_Instructions/Arms_-_primary

I think going through the remainder of the part manufacturing instruction pages and sniffing out more inconsistencies could be constructive both for composition of an eventual word processing draft (whether its continuing the one I have, or one started earlier by Brianna) and for OSErs readily hungering to build the CEB now.

Howard_V_Agnew

Since the work is paused, I have decided to upload the unfinished draft as-is, figured it couldn't hurt. Just bear in mind not only is this draft unfinished, it may get trashed entirely if it turns out Brianna has already started a similar effort.

*THUNK* .ODT file types are not allowed for upload!?

Howard_V_Agnew · Compressed Earth Brick Press - Building Instructions - 2011-09-18.odt

Wow, the IT guys are fast responders. :P

Howard_V_Agnew

I had a pleasant conversation with Brianna (well, she was pleasant, the Skype connection quality was something else...) and it sounds like I am good to proceed. I will add in the various components, and pop questions at her when I find things that don't look quite right. I will also continue posting them here to this thread so you guys also interesting in the documentation can throw your comments and ideas at me. I'm definitely not looking for a perfect rough draft, and I will really poke around to ensure all the instructions and cad drawings I get and put in there are current before I'd export to .PDF for publishing.

I am really hopeful to get in at FeF. It sounds like they might be able to use me for laying CEBs for the hab lab and stuff. Also sounds like it might be roughing it for a bit, but I don't mind. It would certainly be easier to confirm what the current build details are by being there in person.

mjn

I'm glad you cleared this with Marcin and Brianna, Howard. At least they are aware of your efforts now.

- Mark

Howard_V_Agnew

As a bit of an update, I have been extended an invitation to join the FeF team for a dedicated project visit. To say I'm excited is an understatement, heh.

A bit ironically, this will temporarily reduce my time for putting into the CEB press documentation, but I will still be working on it when I can.

I am starting to conceive of ways of collaboration. The specs are out of date for most of the parts, as I've mentioned, so the Sketchup CAD files will need to be revised as new specs become available. I know Dorkmo has worked on some, and I guess some other guys ... it would really help me if I knew who has been doing what thus far, then I could just feed updated specs so instead of one guy having to go through 20+ parts to update (or in some cases create from scratch) their CAD files, a few guys could work on them in parallel. The chief slowdown remains getting updated specs from Brianna ... she has school and other obligations to attend to of course, so I just need to be patient on that. She certainly knows her stuff and has really helped me keep the document shaped to be machinist-friendly in addition to newbie-friendly.

Its really cool to actually feel things starting to come together. Marcin seems pleased with my efforts, and I guess has re-focused some of his team to work again on the CEB press to focus on getting the documentation out on it. I look forward to hammering away at the stuff and getting a completed draft done.

mjn

Congrats. I hope the experience is both positive and fruitful.

-Mark

Howdy, Stranger!

Categories

In this Discussion

Tagged

Open Source Ecology Forums