Author Options:

Documentation Tools! Answered

Hello designers!

I'm doing some research on design documentation and am interested in what tools people use to document their work-in-progress.  

Do you keep a design journal?  Do you video tape / photograph your work?  Do you use any special software?

...and when do you know when your work is Instructables-ready?  How do you determine how much detail to provide in your Instructable?  And what are the hardest parts of the documentation process?

Also, if you're interested in participating in a study about how people document design work, please send me a message, and I'll provide some more details!


dsi cam and screenshots (prt scr)

I use a kind of a journal myself, an Open Office document (since I am unable to obtain WORD), I try to take pictures "in progress" rather then do it all again, after a success. As for detail, I look at it from the point of view of someone that hasn't any experience in that area I am working on (whether it be electronics or pyrography) and put in, at least some of the basics and / or links to where one can learn them.

For me, the hardest part of the process is picking which of the multitude of pictures to use, since try to take more then I CAN use,.

I havent been able to get myself to use OpenOffice since Oracle Acquired Sun, I suppose there is always LibreOffice thugh.

Isn't there one called STAR or something like that?

Thanks for your response!

Could you describe your process for picking which pictures to use, and do you have any tips for streamlining the process?

The picturest that are clearest, show the best perspective (operation standpoint, lack of shadows, etc). I haven't really been able to streamline it much though. Some of my projects take months.....the two I am working on now have taken WAY too long for the complexity (or lack thereof) of them.

Not really any advice for making the process more efficient, but I take a lot of digital pictures, from lots of angles, with different lighting, and hopefully have a bunch of CLEAR ones that show what I want to show.

The absolute best way to determine how much detail to include in your instructable is to have a friend (who has the time and interest... and money) try to recreate your project with absolutely no unsolicited intervention from you. If you're fortunate (and disciplined) enough to be present during the attempt, make note of every time they hit a snag or ask for help/clarification. That will give you a good idea where to improve is needed and likely how much more information to provide.

Hope it helps. Happy building!


6 years ago

I think that it's important to document as you go, so you don't forget any steps or details. I have a couple of half cooked instructables that are waiting for the project to progress. I'll actually go back and follow them myself to remember where I left off.

With regards to detail, I think it depends who your audience is. If you documenting the process to build a tube amp, you probably don't need to go into the detail to describe what a resistor is, as a basic level of knowledge is assume (however it's always nice to include a few reference links to folks can refresh their memory). If you were documenting a beginners electronics project, such as an atari punk console build, you might want to take the time to explain what each part does, as the audience for this may not have that level of knowledge.

I also take tons of (really poorly lit) pics, and name them in order so I don't forget. Sometimes I'll stage some 'redos' if I think of a better way to do something, or if I make a catastrophic mistake. For minor mistakes, I like to leave them in and carefully note them. If I made the error, maybe others will to.  I choose pictures where all the vital elements are easily visible, and I use a lot of tags.  I make sure I capture all the critical steps, as well as any pitfalls or tricks to make it easier.

If it's a project that involving software or computers, I like to use Jing by Techsmith. It's free and very simple to use.  It takes screenshots or short movies, and it allows you to upload them, and send people the links. If I'm documenting other types of projects, I've used Pixton to create user manuals or convey ideas on a larger scale.

I tend to write ideas down on the inside of my wrist during the day, and then either type them into the stickies app on my mac or start a new instructable with the title of the project so I remember to come back to it. If it's something more complicated than a recipe or something that needs serious brainstorming, I normally sketch things out on a sheet of scrap paper. Sometimes these get lost, though. :P

When it actually get to documenting whatever I'm doing, I take tons of pictures. TONS. I sometimes take so many I have to weed out a lot during editing. "Do I really need two photos of pouring ingredients into a bowl?" The only special software I use are iphoto and picasa and the instructables editor.

I normally only know my work is ready after I've read through it multiple times, double checked that there is a picture for everything and addressed any questions I can think of that someone might have.

As far as how much detail to provide - that's a case-by-case bit for me. I like to think about a project like a beginner which helps me give hints, tips, troubleshooting, etc. throughout the instructable. And if I tried something that didn't work so well, I'll offer other ways to go about it.

The hardest part of the process for me is editing. I am always very worried about photo quality, so I spend a lot of time going through multiples to choose the best one. Editing my instructions are just as hard as I have a tendency to ramble on and on and I want to make sure I've given all the right information without giving too much random stuff.

Our conversation has been running around in my head - I'd love to see what you eventually come up with.

One goal I keep in mind is that an interested reader should be able to replicate what you have done. To that end, I like to make sure that the key details like schematics and software are correct.

Additonal background information in the form of block diagrams and flow charts can help others understand your design at a higher level, so they can implement it in a way that they are more familiar with. They may prefer a different microprocessor or they may not have access to the same parts. Giving them more background helps them understand what substituions are workable.

I tend to go overboard with detail, including material that I know many people may not be interested in. I try to clearly identify which sections are not strictly required to replicate the project, but which are instead included to provide the reader background information.

Writing for an audience which is not as familiar with your project as you are is challenging. You have to read and re read what your wrote to pick up on the places where you just assume others know what you are talking about.

Needless to say, all pictures should be clear, uncluttered, and not blurry or dark.
Video clips should be concise and to the point.

I don't keep a journal, I scribble my idea every where, my lecture notes are full with them. I take a lot of pictures, while I'm making stuff, I was doing that even before I was writing Instrutables. Once I finished what ever I was making I decide, whether or not to put it on Instructables. To me the hardest part of documentation is to actually sit down and do it. I like to make stuff and to take picture, but I'm not a big fan of writing.

I have a bunch of different ways I try to keep track of things, but none of it works really well. I use a lot of similar techniques as Goodhart (I use an spreadsheet instead of a document though). For detail, I tend to go a little far. I assume the reader has no knowledge of what I'm writing and try to write for them (which might be why I don't post too much...it's very time consuming). As for pictures, I try to think of what the most important aspect of the thing I'm doing is, and what I want to get across, and try to take a picture of that, sometimes from multiple angles if it needs it. Unlike Goodhart, I tend to like to make a thing first, before I document it. If I make something from start to finish, I feel I have a better idea of what's important and what things I want to get across in the piece.

If you're curious about more and need people as part of your study, you're welcome to pm me.

I'm up for it.