You’ve just finished your project. Well, not finished, but it works and you’ve solved all the problems worth solving, and you have a thing that works for you. Then you think about sharing your creation with the world. “This is cool” you think. “Other people might think it’s cool, too.” So you have to take pictures and video, and you wish you had documented some more of the assembly steps, and you have to do a writeup, and comment your code, and create a repository for it, maybe think about licensing. All of a sudden, the actual project was only the beginning, and now you’re stressing out about all the other things involved in telling other people about your project, because you know from past experience that there are a lot of haters out there who are going to tear it down unless it’s perfect, or even if it is, and even if people like it they are going to ask you for help or to make one for them, and now it’s 7 years later and people are STILL asking you for the source code for some quick little thing you did and threw up on YouTube when you were just out of college, and of course it won’t work anymore because that was on Windows XP when people still used Java.
Take a deep breath. We’ve all been there. This is an article about finding a good solution to sharing your work without dealing with the hassle. If you read the previous paragraph and finished with a heart rate twice what you started, you know the problem. You just want to share something with the world, but you don’t want to support that project for the rest of your life; you want to move on to new and better and more interesting projects. Here are some tips.
Perfect is the Enemy of Good
If you’ve ever taken apart a product and found design flaws or weaknesses, you probably thought “what idiot did this? They should have done it this other way.” Maybe you’re right, or maybe there’s something you didn’t think of, but at least they made something that’s shipping. There are plenty of armchair experts, and they’re too busy criticizing other people’s work to put their own stuff out there. The statistics are pretty conclusive here; a web page that exists has a much higher chance of being viewed than a web page that doesn’t exist. You’ll never please everybody, so accept that your work will have to be good enough, and push it out the door anyway.
The Cardinal Rule: Document for Yourself
Getting better at documenting your works starts by helping yourself. When you’re writing something, you hit save all the time to make sure you don’t lose your work. You’ve trained yourself to do that to avoid hassle later. You can do the same thing with other documenting practices to help future-you.
With code you have git repositories so that you can revert to previously working states. If you are writing code, create a text file to describe the development environment used and how to compile and run the code. Too often I’ve run something and thought “it’s stored in my bash history so I’ll just look through that when I need to run it again” only to be bitten by it later when I move to another computer.
When you’re building something physical, the nearest equivalent is photos. Take photos all the time during the build process not just to document but so that when you screw something up you can go look at an earlier photo to see how it was before. Photos don’t need to be perfect, but you should take a bunch because when you go back to review them half will be blurry, and a quarter will have the wrong lighting and an eighth will be too close to understand what’s going on. Get in the habit of taking photos throughout the build process, because you’re not going to be able to recreate the process if you’re trying to put together documentation later. Remember, you’re doing this for you, not for the rest of the world.
Write less. You don’t need a long dissertation on every aspect of the project. The less you write, the more likely it is that someone will read it. It sounds backwards, but skimming is the normal way people read online content now. Make a quick note for something that is important, something that took you a while to figure out, or something where you explored a couple branches but decided on a particular one. When you come back to it, you’ll wonder “why did I do it this way?” and you want to save yourself the agony of repeating the experiment or scratching your head.
Publishing: Put It Out There!
At this point, consider your goals for your attempt at internet fame. If your goal is millions of views and coverage by major media, you won’t get it with a blog post, but with a professionally edited short video, carefully crafted web site, and complete media package. If you are aiming just to put something out there so that other people like you can check it out, consider posting your project on Hackaday.io (shameless plug) as that’s where a lot of hardware people are publishing, reading, and talking about projects. Your goals should align with the energy you dedicate. For most purposes, though, the following pieces are REALLY helpful for telling the full story of the project:
- A short video demonstrating the project.
- A photo gallery, ideally with captions, and ideally with some glamour shots at different aspect ratios (a wide shot, a square shot, and a tall shot).
- A writeup that includes the backstory, design considerations, build process, and results, with ideally some snippets about interesting problems encountered or clever solutions, or in general things that are noteworthy and unique. This should not be too long.
- Links to appropriate repositories/files/libraries.
- A license (makes it known how your work and be reused without the need to contact you first)
We’ve set up Hackaday.io to make all of these steps easy, but there are myriad options like imgur for photo galleries or hosting your own web site. The point is, get your hard work out there so that others can see what you did and how you did it! And again, this will help future-you find all the relevant information if you pick the project back up a decade from now.
The Long Tail
Years after you’ve put your project up, people are still looking at it and contacting you with questions. It doesn’t matter how much effort you put into it, and sometimes the more effort, the more likely you will be frustrated by people who ask questions without reading. Assume that there will be people who will write to you no matter what you put out there, and that their questions will annoy you, and that they will ask you to do more work. You need to figure out some general rules and boundaries. Here are some helpful ones:
- Ignore trolls. It’s hard and I feel it in my gut for hours, but you should try to associate only with positive and supportive people who will make you feel good about your work.
- Respond to praise. If someone writes to tell you something positive, thank them. They put effort into making your day better, and we need to support more of that.
- Answer questions briefly, with links to the appropriate location in your documentation. Not passive aggressively saying “if you had read the documentation, you’d know…” but more like “great question. The short answer is you put the dongle in the framulater counter clockwise. I have more detail on the project page on this particular section.”
- Don’t try to answer lazy questions. “It doesn’t work” deserves only “bummer. What have you tried?” If they don’t put in the work to ask an intelligent question, you can’t be expected to try to answer it.
- People will ask for feature upgrades, suggest that you should do this or that, or ask you to get it working on a different platform, or partner to make a commercial product. Consider this at your leisure, but remember that when this happens, the project you did for you is being turned into a project you do for someone else. You may want to do due diligence about their value as a partner, and check your values to see if continuing to work on this project for someone else is aligned with your interests. If it doesn’t, you might consider charging them for your time since what you’ll be doing will have become work. You can say no to people and wish them luck on their endeavor. After all, by publishing it as open source you’ve already contributed to their project by making yours available.
Manage Your Emotions
When I post something to social media, for the next couple days I check regularly to see how well it’s doing. Most people seek approval or validation from others. Positive reactions make us feel good and worthy and talented, negative reactions make us feel like crawling in a hole, and no reactions make us feel like we’re unappreciated and wasting our effort. We are unlikely to feel satisfied with any number of views because we see the YouTube stars that get millions of hits on their videos of themselves trying on different hats, and we score at best a few thousand. We can quantify views and comments, so they become the measure of our success, and they’re almost never quantities that please us. It’s rough, it sucks, it’s not fair.
And yet, in the beginning this project wasn’t about hits. This project was about doing something cool, and putting it out there was an afterthought. I still have this really cool talking fish on my wall. Don’t get caught up in the popularity of your project; popularity wasn’t an important metric at the beginning, and it shouldn’t be at the end. Instead, focus on the positive feedback, and the satisfaction of having built a thing with your own hands.
Don’t Keep it a Secret
Setting a minimum goal for publishing info about your projects publicly is a great thing to add to your workflow. Approach it from a selfish standpoint: this is the information you yourself will need to pick the project back up at some point in the future. Collect your design files, pictures, videos, and notes together in one place and you’ll be able to pick it up again pretty easily.
This becomes a benefit for everyone else working on something similar. You don’t always know what the most brilliant part of your design is, and you may be surprised by what details others latch onto and run with. And seeing a derivative work that’s really awesome feels great! Make that possible by choosing a license for your work that tells others what your preferences are in using your open source work. (How can it be attributed? Is it for commercial or for non-commercial use? Should derivative works also be shared?)
Grabbing a few of these suggestions will relax the anxiety sometimes felt with putting your project out into the world. Building stuff is cool, and so is showing it off. Take a deep breath and feel great about sharing the story of your work!
I’d love to hear about your own habits and experiences in getting your projects out into the world. Share your stories in the comments below.
One thing will help a lot. Just don’t care what people think. There will always be critics and morons and aiming to please them is a pointless waste of time. Have your own personal high standards, and once the project meets those, make it available to others if that is what you want to do. My experiences doing so have almost all been positive. Actually maybe they ALL have been positive. You Tube seems to have developed a nasty and vicious culture. My advice there is simple, never read anything in the comments section.
Constructive criticism.
“One thing will help a lot. Just don’t care what people think.”
Who cares what you think!
B^)
Surely You’re Joking, Mr. Feynman!
What Do You Care What Other People Think?
I enjoyed reading that book a couple decades ago, and recommend it to any HaD reader who hasn’t already done so.!
Which?
Both! I’d forgotten that was two different titles.
Read Both!
I loved Dr. Feynmann’s finding about the meaning of life. Very Monty Pythonesque and absolutely true.
> never read anything in the comments section.
Oximoron.
Giving advice in a comment section, what nobody should read?:)
^oxymoron^
although I’m not sure if it is the proper word to use in this context.
What do you say, Tarkhan Thesaurus?
We could use some oxYgen in here.
a) The advice will only be seen by those who need it,
b) He obviously isn’t taking his own advice!
That really resonates with me, I publish things so I don’t lose track of them, but I sometimes spoil it by caring too much about the likes. On the other hand, there are some things I have published and can go back to when I am looking for a little pick me up and remember the project, and some of the people it helped.
I have tons of code in various places and I’m not really sure how many folks are using it. It’s really for me should I need to find it at some later date. Some of my code isn’t very good but it works other parts of my code is better. I’ve had a few people ask me about and and provide fixes. I’ve added and given credit for the code. I’ve helped a few folks but there are somethings I no longer work with (X10). I can pretty much ignore folks if I need to (email filters or just turn a blind eye). I’ve got plenty to do and lots of things to ignore. ;-)
Words of wisdom, well received.
Licensing is easy for me, I usually just release everything as public domain — the few times I actually release anything publicly, anyways. Actually putting any of my stuff out there in the public is… unnerving, though. I have pretty much no self-esteem and I know already all by myself that I am a moron, I do idiotic mistakes and I just have no skills, so then someone coming along and berating me even further just pretty much makes me not want to share at all.
I think the mistake we make is assuming the people we respect don’t do stupid things. Everyone does stupid things… the real judge of character is how you handle that. Recognize the occasional goof, own it and learn from it. I think that’s the path to self-esteem, striving for the brilliant moments and forgiving yourself for the funny ones.
I look back on some of the code I’ve relased into the wild and is shocking! I know because I’ve had to go back and work on it some time later lol.
But I think I’m getting better – and getting better at documenting as well which realy helps, especially when some one asks me about x project a few years down the track. Or I need to modify it later
We are what we do, so please do not suffer from low self esteem if you not only do, but also share.
It is the doers who make the world function, not the talkers, all too many of whom suffer from an excess of self esteem.
Life is a journey, and we are a work in progress, as is any code or design published at a point in time. If it is fit for purpose and satisfactorily robust, then be content and pause to pat yourself on the back, to confirm that your most important critic approves.
As for criticism, was it not Friedrich Nietsche who said “Anything which does not kill us only makes us stronger.”?
(And my father often quoted “A strong kite flies best in a headwind”) The attitude can be absorbed – in time.
Oh, and the only one who makes no mistakes is he who does nothing. We learn more from our mistakes than our successes, so they are valuable.
“Collect your design files, pictures, videos, and notes together in one place and you’ll be able to pick it up again pretty easily.”
We’re still waiting for a feature on hackaday.io to retrieve/save/backup our works to a local or another remote location.
My script https://hackaday.io/project/8536-hackadump is broken at each update of the site’s framework :-(
Cool project. Was just wondering what hackaday.io’s policy on those that make objects that people can potentially use to harm other people is. Do gun/bomb/other dangerous item projects get deleted or just hidden?
+1
This is an excellent post, thanks Bob. I know better, but I recently (ironically?) fell into some of these traps entering one of my projects in the Hackaday Prize.
For me, I really enjoy the work (as opposed to the rewards) and try to treat the outcomes like “waste heat”: worth recovering if useful (especially to others), but not something to focus on generating deliberately.
Re. the part of the “Long Tail” and the rules :
Decide on a good set of rules ( you can improve them later ) and STICK to them. If you later decide some of them need changing, you can change them. But do not break them every time someone asks, or the problems will stay with you.
As an example, if you sell something on ebay, and decide not to offer free shipping, then do not offer free shipping, no matter if people ask, beg, thread, cry, call you names, whatever. You took your decisions based on your knowledge of pros and cons, and we expect all of the ramifications were considered. So, do not decide on a different thing every time, because it WILL bite you.
I person I exchanged a couple emails with decades ago had built a low cost PIC programmer. He may still have it on his site, but has a link to another device that is even better than his.
s/I person/A person/
I finally learned how to use Vim this year ????it’s great. Even if I don’t have the use or memory for most features.
Think that’s a sed function, but it might be callable from him.
Use FOSS both personally and professionaly. Have contributed to FOSS. Have provided support via answering technical questions on some forums. But am reticent to publish any of my stuff as OSH, as no good deed will ever go unpunished. Humans are difficult, demanding, and generally dangerous. Proceed with caution, do not swim immediately after lunch, and treat your dog well.
+1.
Treat your dog well.
Words to live by.
Personally, I come up with projects that I think “oh, this is the sort of thing hackaday might feature” and document those pretty well, and the ones that I don’t think a largeish site would like, get very poorly documented. The knowledge that a lot of other eyes might be looking at what I’ve done is very powerful motivation.
I keep thinking that if I had something like google glass, that was an easy, convenient way to have a camera pointed directly at what I’m looking at, that would be a tremendous help in documentation. However, editing video takes at least an order of magnitude more effort than just taking pictures.
I’m still supporting (even if it’s not frequent) an open source project I started releasing 10 years ago. The occasional help from other people is a morale boost and most users are nice, supportive and understanding. It helps a lot. As I use a language that is not trendy anymore (Delphi), it’s difficult to find people motivated enough to pass the relay. On the other hand, nobody ever questioned my poor coding skills (every perks counts).
I made it very clear to the users that I cannot afford to dedicate as much time to it as in it’s heyday and most of them accept that. I had a few unhelpful or rude feedbacks, but I’m the biggest ass-hole in town so I just ignore them.
The tip about fixing rules and following them is golden, because if you cave once, people will get in the breach and ask you for the moon with puppy eyes. No is a perfectly valid answer that you can give politely.
“I’m the biggest ass-hole in town so I just ignore them.”
I take this with a grain of salt, but this is absolutely the key. The trick is to have a tough skin without being a total A-hole. Or as one fellow told me his thesis advisor once told him: “One of the keys to success in life is knowing when to be an A-hole”.
I am still learning how and when.
Naturally know who you’re being an A-hole to. If the person across the table is a former hit-man for the mob? DON”T be an A-hole to him.
“You’ve just finished your project. Well, not finished, but it works and you’ve solved all the problems worth solving, and you have a thing that works for you. ”
I’m glad you started there. But the haters start even sooner. They want you to open source things that aren’t even finished, that don’t even execute all of the problems that you’ve solved in your head. The problems there then become the support nightmare of “how does this [unfinished] part work?” and “why does it suck [because it isn’t finished yet]?” and “I created a pull request that implements [something you planned on doing a completely different way and now this ruins it]” and “why didn’t you think about [thing you totally thought about but it isn’t written into the code yet]?” and on and on
That’s why I’m happy to think about opening up some of my software projects, but NOT open to Github. If you want to modify my code for your own purposes, knock yourself out. But don’t expect me to value your changes, just because they were useful to you.
You can solve most github problems by turning off email notifications, and then just don’t read pull requests. :)
Or better yet, delete/close them
And then there’s the cautionary tale that needs to be studied by all considering opening up their projects: ffmpeg vs. avconv. For those not familiar, ffmpeg is a very comprehensive set of tools for converting between video formats. One guy was the head of the project, and a splinter group formed based on objections to decisions that that guy made. This group forked the project and renamed it avconv. BUT, they went a step way past the line: they declared their fork to be the true ffmpeg, and went so far as to convince the Ubuntu people this was the case, to the point where on some Ubuntu releases, if you type “ffmpeg” at the command line, you get a message stating that ffmpeg is obsolete and has been replaced by avconv. Very bad karma.
Irfanview
Irfanview appears to be a Windows-only still image converter. Ffmpeg is an open-source tool set for motion pictures. If you’ve used Handbrake, you’ve used it; it uses the ffmpeg libraries. If you’ve used Avidemux, you’ve used ffmpeg. If you’ve used Kdenlive or Shotcut, you’ve used ffmpeg. Same goes for many other video applications (ffmpeg itself is a command line tool; many people have incorporated it into GUI applications).
Good LORD, what a mess! https://en.wikipedia.org/wiki/Libav#History
But… petty politics is the BEST PART of open-source development!
Just ask the EFF…
A less-representative group of the masses I have rarely seen.
About hackaday.io, as one who only uses it to see more information about something featured at Hackaday I have to say .io is pretty poor. Either the platform is poor or those using don’t know how to use it. Often I go there to see a project and up thinking the maker should have have used a forum post to outline their work, using one of the many free cloud services to share documents. Having a hide much thickerr than the current POTUS has, and having in general a KMA attitude barbs don’t reach nere endings. In the past I have posted in forums dead simple code that did calculations that others find hard to do. in one forum I outlined to a woman to go about trouble shooting an underground electrical service entrance that was a suspect in a higher than expected electrical bill. Her response was that she wished I lived closer to be able to do the trouble shooting. the other positive response was another member of the group backing up my recommendations.
People still use Java – a lot :)
Props to you for keeping going – I gave up trying to correct those who think Java is dead because Java applets are dead years ago…!
I only use analog java.
I feel like this was a bigger problem before the likes of distributed version control / CI hit the masses. Years ago with CVS / SVN, getting people to contribute was either a case of creating a patch file that had to be very painfully merged only to find it never worked.
These days, if someone suggests a feature or points out a bug, my first comment is usually along the lines of “sounds like a great idea, feel free to create a PR!” You’d be amazed just how many people drop off the radar entirely as soon as the idea of them, rather than you doing the work becomes apparent…
Maybe you understand your code better than they do, especially the larger it is. e.g. Mozilla.
I still have people emailing me over the NES Laser Gun from 7 years ago, trying to make their own. I figure if they can’t figure out how to source the parts, they aren’t smart enough to source some OD3 405nm blocking goggles for protection.
“…when people still used Java”
I still use Java. But Java mortally wounded itself by refusing to implement complex numbers and hardware floating point (single, double, and long double). They just dropped the ball, and industry moved on.
So now everyone (with common sense) is moving to Julia.
A lot of people have this feeling, this need to publish, but even more people sometimes prefer to keep it closed up to when it is fully copyrighted, patented or whatever. And at this point publishing became marketing.
But I think this happens when you have something done in a such a nice way that may lead you to some recognition. And we also know that it is not necessarily a danger, since the idea is 1% of the work, the rest is implementation.
I never did something amazing in projects, but I think that I will ask the question to myself: I like to let the world to know my project, but can I tolerate if someone takes all the credits because was better in the implementation than me, copying my work? What if makes a lot of money? And maybe not necessarily in a good way?
I would like to hear opinions, I am clueless.
My issue is that by nature I am a lazy perfectionist, so just the thought of all of the work it would require to properly document what I’ve done to my standards absolutely exhausts me. I would need at least 100 people throwing $50 each in my direction before I would even start, and most of that would go towards hiring someone competent to act as director for the production. :sigh:
Oh, and when taking pictures that you might publish some day as part of your documentation, make sure that you don’t accidentally have items in frame that have information that you don’t want published, like envelopes with your full home address or your gps coordinates…
I have a seriously cluttered desk and in the past I’ve had to spent non-trivial amounts of time editing images to get these accidental leaks out of frame.
Now, I just swipe enough stuff out of the way to have a nice rectangular area that i can crop of I chose to share an image with the world.
Just a bit more to go with
dhaveniths good thoughts on the work place hygiene.
Don’t forget about any reflective/shiny items.
Identifiable items and or people can be reflected by them.
Visible television or web feeds/sites can accidentally give locality information too.
“Customized” desktop backgrounds can help identify you also.
This poat happened at a time when I am agonizing slightly about three separate camera projects about which I am both proud yet need to document. I even have a bit of code. I’m traveling and these daunting tasks cannot be accomplished on my cell phone / tablet. BUT I have pen and paper, and I need to stop procrastinating. And I can make a video in an amazing location. The anxiety is real, but I got this. Thanks!
Do stuff to do it.
The motto my dad taught me and I live by. It really works out well for today’s social media world where everyone is worried about likes and how things will be received.
I rarely post my projects online because I am shit about documenting them because I am just building something and not out to make a tutorial for someone else to follow and don’t need to rub my nipples to a picture of a re-worked relay system shot in 30 megapixel glory. I also learned early on that I do not enjoy answering emails about resistor values or code from a nearly ten year old post for people that cannot even bother to say “thanks” or just want to prove how smart they are to themselves.
Thanks for reminding me about “Perfect is the Enemy of Good”. It’s so easy to get bogged down squezing out perfection for the last 10 or 20% with little to be gained in the overall quality.
Great words of wisdom, Bob.