A Rant On Personal Software Projects

Looking across your hard drive and GitHub, you might find hundreds of notes and skeletons of Git repositories. A veritable graveyard of software side projects. The typical flow for many of these projects is: get an idea, ruminate on the idea until it becomes exciting, eventually becoming more exciting than the current side project, notes are captured, a repository is created, and work begins at a blistering pace as the focus and excitement are there. There might be some rewrites or some changes in direction. Questions of whether the project is worthwhile or “what even should this project actually be” start to arise. Eventually, enthusiasm wanes as these questions continue to multiply. Progress slows as the path forward seems less clear-cut as it once did. The project is either sunset with a mournful promise to someday return or quietly put aside as something new and exciting comes to take its place. Sound familiar? Perhaps not, but the principles here could be helpful.

This particular article is largely a piece of opinion from one engineer to another. It’s about engineering the process by which you design a project to have better outcomes. There are many reasons why a project could be shelved or scrapped and not all of them are from a lack of clear project definition. In the case where it isn’t clear what the project is, it can be helpful to think about it in a more holistic/meta sense. There are two types of personal projects in broad strokes: technology demos and products.

0b10 Types of Personal Projects

A technology demo is about the tech or the how. Perhaps you’re trying some new language or a new algorithm. It’s okay for it to be half-baked and clunky because that’s not what it was designed for. It was designed to be beautiful and interesting on the inside. In a way, when you step away, the project is complete because you got what you wanted: learning.

The rust language logo being branded onto a microcontroller housing
Trying out Rust on a microcontroller is a fine reason for doing a project.

In contrast, a product personal project focuses on what it does and the experience as an end-user interacts with it. Maybe it has a great README, a slick user experience, or does something better than anything else out there. The point is that it is focused on the end-user that uses it rather than the person who makes it. It doesn’t particularly matter what it looks like on the inside. It could be based on COBOL and be a tangle of spaghetti internally. Clean code helps with maintenance and project longevity, but it does absolutely nothing for the product experience.

In a nutshell, it is about designing the project experience rather than simply the project itself. It begins at a more abstract level, starting with how you will approach this particular idea. Is it a tech demo or a product? Is this a project that’s an easy win? With these sorts of things in mind, you can start asking better questions. Questions that allow you to design what this will be. By being intentional about the process by which you make something, you directly influence the thing you make.

Let the Right Question Be Your Guide

A BB-8 style robot
This robot looks awesome! If it’s all loose wire and hot snot on the inside, does it matter?

For a product, you need to ask who the end-user is. Even if the user is you, that doesn’t mean you are static. Old bad code written by yourself is utterly mystifying; why wouldn’t an old, poorly designed product do the same? A product is about the end-user, not the developer, even if those two are the same person.

Another good question would be, if Hackaday wrote about my project, what would they focus on and write about? (I’ll follow that up with “have I included clear, high-resolution pictures for them to use?”) As an end-user, what is the desired experience and how can it be simpler. It can be helpful to write these things down.

Come up with a concrete plan, don’t change it or allow the scope to creep. If problems come up, go back to the questions you asked earlier and then redefine the scope. Try not to get distracted by the technology, and instead focus on what you’re trying to do. Don’t get too sucked into the how. A great example of how a product is designed and made is the Flipper Zero.

For a tech demo, have fun with it. Want to throw something else on there? Go for it. Perhaps you’re trying to learn some WebAssembly by porting Doom. There is no scope creep as there is no scope. As mentioned earlier, the focus is on the developer, not the user. Usability is not the focus here. Questions might be “what would be most interesting” or “how can I skip over boilerplate?”

But What Do I Know?

Of course, this is all just one writer’s opinion and has a sample size of one. It’s possible for a project to be somewhere in between a product and a tech demo, or neither. Nevertheless, adopting some of these methodologies has led to much more satisfaction with side-project endeavors. Do you have a different perspective? When you accomplish the goals you set out, do you move the goalposts or step back to tackle something new?

41 thoughts on “A Rant On Personal Software Projects

  1. for the project usually dies in 2 ways. 1) when I do search to figure out some messed up syntax or trying to add some function/feature to the program. Excited yes to get it to work and while doing a search or two I come across a free version that I can download that does what I am looking for. 2) when I look at the honey do list and realize I need to get something done there before the season changes. Only have got a couple of things on github since I mostly use VS 2019 nowadays, but I still haven’t figured out how to seamlessly make that process work to upload files from the VS 2019 IDE yet and really not worried about it. The first project I uploaded (a few years ago) was way easier then it is now.

        1. I will agree that the vscode merge conflict resolution support is stellar. I do most of my git at the command line but I find myself frequently using vscode instead of git mergetool invoking kdiff3 or meld

        2. correct I am using the VS2019 (community) version, the last time I tried integrating with git it was a huge pain and never got it uploaded, even when trying to follow along with a couple of youtube videos. Maybe it’s a community version thing though, but I still suspect it’s me. It just seems to be harder then it needs to be. I had an easier time getting an Arduino project uploaded, but that was just through the git website interface. I haven’t tried the command line yet.

  2. This can go in many many directions. There is nothing unique to software here. You can be a woodworker, welder, or machinist and have unfinished projects cluttering your workshop. Some of the smartest and most productive people I know have offices that look like a bomb went off. Too much organization and planning can smother innovation. But people are different and can work effectively in different ways. Not all projects deserve to be finished, some serve their purpose by teaching a lesson and the best thing is to pitch them in the dumpster and move on.

    An extra github repository doesn’t clutter up my workshop though, and an unfinished project with substantial investment can be useful for reference if nothing else. Sometimes the problem is like piling too much food on your plate at an all you can eat restaurant — your eyes are too big for your stomach. But an ambitious project is a good way to grow.

    1. Interesting point that repos don’t clutter up your workshop. On the other hand, it’s really easy to push a new repo and forget about it for several years. Finding it again, and being able to pick up where I left off, have both been issues for me. I’m trying to do better on populating the readme.md with bread crumbs for myself. Yes, comments in the code should be helpful, but the repo in general needs a guide or future me is going to be crabby.

        1. Comments require practice to write well, so it’s a good opportunity to practice. My favorites are “PDL” from Code Complete (ISBN: 0735619670), which is broadly “describe the algorithm as comments and then fill in the code” or even better: “comments are the requirements”, i.e. what the code *should* do, not what it does or how it does it. Also helpful is to write the comment for a method before giving it a name, which leads to better method names once the comment is complete.

  3. I disagree with this article pretty strongly. I work for one of the big tech companies and the overhead is exhausting. The process you have described here for managing side projects is a short form of my day job as a software developer- harassing PMs, managing scope and deadlines, and trying not to stray the course from the end goal. I find this to be exhausting, not a good use of my skills, and it impedes my ability to release the creative urge.

    My side projects are just playgrounds for me to try things out so I can release the creative energy I don’t get to use in my day job. I’d much rather have a graveyard 20-80% complete projects than attempt to manage myself in my limited free time. Work is work, and side projects are play.

    1. What your describing as “side projects” sounds like it falls under the tech demo/learning project categorization of the article which the OP provides really relaxed rules on. In my own experience as a developer I used to have a job that was super unsatisfying creativity wise, so I wandered into 3d printing for my side projects. With the exception of simple trinkets I printed for friends & family members, almost nothing I printed had “I want to print this thing” as it’s primary goal. Almost all of it came down to “I’d like to figure out how to use x tool better while I solve y problem”, so you could argue it was almost exclusively tech demo/learning project. Only a couple times was I making “serious” prints and to be honest most of those were figuring out how to tune someone else’s model for my needs/printer.

    1. I agree. If you’re playing around then it’s play and who cares if it ever gets finished… outside of your significant other anyway, who likes to remind you about finishing what you start. To which, like every other spouse in the history of mankind, one suddenly becomes deaf.

      Technology hobbies are just like any other hobby. At least the only thing lost with set aside entirely software projects is time.

  4. The other big item is INTERUPPTITIS. How many times has a project that is going well got interrupted by something that is deemed more important or critical. The result being the original project never returns and withers on the vine…..We all have experienced that.

  5. Exactly the way it should be.

    You know how you write a novel? You keep writing. You know how you write a good novel? You throw away your writings.

    The vast majority of authors have written a ton of short stories, partial stories and musings that never see the light of day. And then, one day, a story interests them enough to put the time and effort, and their current level of experience all together and they write a manuscript that they believe in more than the collection of words deserve. Then it gets edited and rewritten until another human being can actually read it and have it mostly make sense.

    I say this because so many people have the wrong idea, they think a project idea simply grows into a completed vision through straightforward application of hard work. It can’t grow to completion without hard work, but the path isn’t straight, and the skills required might be just outside of reach at the onset.

    Now, get back to writing code you’ll later abandon, it don’t write itself.

    And maybe, just maybe, the code will start to evolve beyond the initial concept and continue to grow with fresh ideas.

    1. I set out to build a desk last year, since starting I’ve also started 2 volume control boxes, an electric guitar (spare wood) .a second electric guitar based on the technique for the desk, built a wood/steel/3d printed router planing jig, came up with a template for a guitar I could snap together, transposed those onto plywood and am now starting a bigger router sled.

      Really that’s all one project, I’ve just got a lot to learn.

      Started a ton of other stuff I’ve not finished in the same time, but I’ve learned something every step of the way.

  6. I have a project that deals with exactly these issues. It uses psychological techniques to rekindle motivation for finishing your paused projects. It’s in beta now, it should be publicly available next Monday (9/20).

    https://hackaday.io/project/180726-motivation

    The project is based on psychological research and attempts to leverage what we know about motivation. It’s experimental, basically “my guess” on how to interpret and leverage the effects, but the beta tester reports that it is having a positive effect.

    Basically, there are two types of motivation: intrinsic and extrinsic. Extrinsic motivations are what you get in exchange for being done: money, likes, a promotion, and so on.

    For various reasons, explained in the syllabus of the project, the excitement from extrinsic motivations will fade with time – frequently in a couple of days. This is a well-known effect called “the hedonic treadmill” (google that).

    Intrinsic motivations come from doing the project, and come in 4 categories: artistic control, learning something new, practicing something you’re rusty at, or personal value (to you, your family, or the community).

    Develop your project by focusing on the extrinsic rewards, basically the value at the end, will leave you adrift if you can’t complete the project before the hedonic adaptation sets in. Basically, if you can’t complete in about 3 days, you’ll lose interest. This frequently happens if you have to order parts online.

    Develop your project by focusing on the intrinsic rewards, basically what you learn and the value of the final product in your own life, and you have continuous motivation that can carry you to the end.

    To the point in the OP, it helps tremendously if you wait 3 days after getting an idea. This gives the hedonic adaptation a chance to wear off, and at the end you can make a rational decision. During this time, carry around a notebook and sketch out the project – making changes and improvements as they occur to you. No project comes into the world fully formed, and making improvements in the beginning will save you a lot of time later.

    Having a well-defined and visual representation of the project goals (after the 3-day period) also helps tremendously with project completion. It programs a goal-seeking section of your brain (reticular activating system – google that) that encourages you to finish. Having just a “general feel” of where you want the project to go won’t do that, and it makes completion much harder.

  7. Even the github graveyard has some value, when I look for examples for a particular case, I almost always dig up some bones of fossils repository that help me going further. My own success is often based on other peoples attempts, even if neglevted, unfinished, awfully written.

  8. Open source projects are not paid full time job, so there are very little incentive for it nor actual dead lines.
    Looking at my own projects, the ones that get done are always out of my needs. I don’t do trivial me-too stuff. I picked hard projects so that I can push myself. I am more likely to run into a few barriers on the software side or lost interest.
    With COVID affecting components availability, shipping, cost of living and stress, I don’t think my projects would get anywhere.

  9. I have been doing lots of workshop cleanup lately. And you know what I find in many of my mystery boxes? Unfinished projects. Only a small fraction are worth finishing. Some I have no interest in any more. Others I would do now in an entirely different way. Every one of them had its time and place and taught me something. Every time I pitch one out, it releases something in my mind I didn’t know was there.

    So yes, I would disagree with the idea of putting more hurdles and beaureaucratic BS into the lives of hackers as a methodology for finishing projects. Just say no to that kind of stuff.

    Comments in code. I write these only for myself. Comments contain information that a competent programmer could not get from the code itself or would have great difficulty doing so. This is a whole ‘nuther topic. I have found comments in code I wrote 10 or 20 years ago (that I wrote) and thanked myself a thousand times for writing them. I have found treasures in comments written by other people. Discouraging comments (Linux kernel, I am looking at you!) is penny wise and pound foolish.

  10. you know, when i was in college i had to struggle to learn how to quit, how to drop a class if i didn’t like the prof, or to drop out of a bike race when training started to harsh my buzz (the team collapsed around me and saved me the trouble). but i don’t think i’ve ever felt any hesitation or regret about dead personal projects.

    my projects are almost exclusively useful, or to-be-used, even the proof-of-concepts. like, last week after the hackaday article about print-in-place slide puzzles, i designed&printed one of my own to break the ice on print-in-place, a technique i’d never tried. it was a 3×3 and even my 7yo figured it out the first evening so i printed a 3×4 to refine the print-in-place characteristics, and to see if it would be easier or harder to play (it’s almost the same, but more engaging). wife and i have both pretty thoroughly mastered the genre, playing with it this past week. the toy is almost boring and i’ll probably never print another.

    so a lot of my projects with no recent changes, they simply work. i check in changes when i buy a new laptop and have to recompile them all from source against modern libraries.

    others get abandoned because i stop having use for it (i haven’t used my soft synth in years, i have been playing acoustic instruments). or because i find/make a better tool (i’ve made and discarded so many unsatisfying interpretters and compilers). but that doesn’t feel to me like the project died, just that the soul of the project moved from one repository to another. i made a DAW (audio sample cut & paste & mix) 23 years ago that i found profoundly disappointing to use. i used it nonetheless the few times i needed one, and now i’ve designed its successor and i don’t consider that abandoned, it’s merely waiting for a contiguous block of free time. 22 years in between with no progress, and i wouldn’t call it abandoned. hah!

    i’ve got android apps i made for myself, that i published for others…and they each have lengthy todo list of meritorious features other people have asked for. some of those changes will languish for years but the fact of the matter is, the moment i get a new phone with android 13 or whatever, i’m practically guaranteed to fix the things that pop up. it’s not abandoned, it just isn’t being updated until my old phone dies.

  11. I find often purposefully distract myself when work is going slowly or my programmer(s) need a rest. I think the important thing is to keep focused on the end goal, and realise that if the end payoff is worth it, delays are acceptable and a way to take stock and maybe do a bit more research.

  12. the only thing i ever put on github is my 16-bit arduino joystick library. most libs aimed for the 10 bit adcs on the arduino itself, but a control freak like me needs moar bits.

    needless to say my code folder is about 2.5 gigs of long forgotten projects, none of which have come to any level of completion, and many are just duplicates where i tested something that might break the main code base, if only i could remember which copy that was.

  13. github could assist with some governance where it essentially divides github into two halves – mature projects with staying power and indication of vitality (e.g., recent and frequent commits), and then everything else

    new projects would always go into the dung heap side of github, and constant measuring of project metrics would algorithmicly and automatically determine what gets to be promoted into the shining hill side of github

    metrics:

    how long has the project existed
    how many committers
    how frequently is it committed to over time
    how recent latest commits
    how many clones of the project are there (or download of key build artifacts)

    And how about I slip some money to github on the side and they put my project into the shining hill github? Well, this is certainly a very old (ancient) criteria basis

    1. No way. Just use filters to sort by most stars. Github is pretty good compared to other social media type sites. Don’t go messing it up with these ideas. I only need to go through a couple pages to see all projects with any traction even with broad search terms like web dashboard. I just had the catharsis of moving away from azure webhosting. I worry microsoft will mess up github too. And implementing anything like this bifurcation would be a bad sign.

    2. i love that github doesn’t do this. it can be hard sometimes to tell which version is the canonical version, but that’s not really what github is for. i love that if you look for a project on github, you can find people’s private forks that are just maybe one commit different from the main one. a lot of times, this is a nightmare, but sometimes, that one commit is just what you’re looking for even if it wasn’t worth integrating into the main version, or even if the main one is abandoned. and for really small projects, it allows a fluid sense of what the main branch is. which is really valuable because the different developers may be at different stages of stutter-stop development.

      github doesn’t do the project maintainer work of integrating all of the disparate forks, if you want a canonical version you still need someone to do that work. but if no one has done that work, github at least lets you see all the pieces. it’s helped me out of a couple jams, especially with niche hardware that no one bothered to properly support.

  14. What I need is a way to index the important things I learned in the “github graveyard” so I can find them again. For example, I’ve been playing with Arduino and Raspberry Pi and Raspberry Pi Pico etc. etc. (Also “higher level” language forays, but the concept is the same). I may decide to create a new project, and think: “I know I programmed a quadrature encoder before, where is that code…” Right now the only way I have to (maybe) find it is firing up “Everything” search and give it an extension of “.c or .h or .ino” and content:encoder and hope I can find the relevant file. Short of developing a discipline of meticulous lab notes, is there any good solution to a bad wetware memory?

Leave a Reply

Please be kind and respectful to help make the comments section excellent. (Comment Policy)

This site uses Akismet to reduce spam. Learn how your comment data is processed.