Photo by Sincerely Media on Unsplash
How to Blog Your Portfolio Projects (and Courses!)
How blogging your projects helps you learn and optimize your job search
If you're like me, when you've finished a project or a course you're very ready to slap it on your portfolio and start something new. But if you don't write up a blog post about the project/course, you're leaving so much value on the table! Blogging my courses and projects got me my job, in fact.
I came to the tech industry via academia, and was planning to become a data scientist. Fortuntately for me, I came across fast.ai very early in my journey, and read Rachel Thomas' post Why you (yes, you) should blog. I think for many people the biggest barrier to writing is the conviction that we have nothing to say, or nothing anyone would want to read. But as [Rachel says]: "You are best positioned to help people one step behind you."
So as I wrote, I was writing with myself as an imaginary audience. I wrote what I would have benefitted from reading prior to or during whatever lesson or project I was working on. If I had a question and found an answer, I wrote that up. If I had a question and didn't find an answer, I wrote that up too. Most of my posts didn't get many views, and that was absolutely fine.
How blogging helps you
Writing down what you've learned helps you retain it. It's a form of spaced repetition, and even better, helps make stronger associations in your brain between concepts. And if in a few months you have forgotten some of the details or you can't quite remember how you solved a particular problem, you can read your own post to jog your memory! I've done this many times.
Blogging your projects also increases the quality of your projects, because knowing you'll be posting your thought process reminds you to slow down and keep track of that thought process.
How blogging helps your career
Being able to show prospective employers a project shows them you can complete a project, but a blog post about your project shows them how you approach a project, which is at least as important! Hiring managers want to get a sense of what working with you is like. This is your opportunity to explain how you:
Choose a project Why did you choose to build this in particular? Maybe it was simply the next project in a course you're completing (totally valid!), or maybe you wanted to work on a particular skill or learn how to use a new tool.
Approach a project What were your goals in completing this project? If there were any choices you had to make about which tools you would use to build your project, how did you decide on the ones you used?
Handle roadblocks If you can build a project from start to finish without running into situations in which something doesn't work the way you'd expected (or at all 😁), you're literally wasting your time with that project. So don't be embarassed or shy writing about your roadblocks: overcoming those challenges is the job! Hiring managers know that, and they'll want to see how you respond when you bump into a roadblock:
Do you know how to debug your code or search for error messages you get? - If you can't debug it on your own or find an answer to your question by search, do you know how to find people who can help you, e.g. a forum?
If you've tried everything you can think of and are still stuck, do you move on or keep spinning your wheels? (hint: moving on is the correct answer!)
Check out my post on implementing the k-Nearest Neighbors algorithm from scratch for an example of all of the above!
How to Start a Blog
Starting a blog is only as hard as you want it to be! If you already have a personal site or are comfortable self-hosting a site on GitHub Pages, for instance, great! But if you don't have web dev experience or you just don't want to use your time that way—an absolutely valid choice—platforms like dev.to and Hashnode do all the heavy lifting for you.
How to not start a blog
Agonize over which platform to choose, SEO, canonical links, etc. I'll be honest here and say I still struggle with this, and would have published this very post sooner if I hadn't spent time trying to figure out an optimal workflow to write it in Obsidian, push it to GitHub, and have it land in Hashnode. I'll get that working eventually, but holding this post hostage won't get me there faster!
Questions Your Project Posts Should Answer
Why you're doing this project/taking this course in particular
Which tools you're using, and how you chose them
What your goals of the project are (including learning goals!)
My blogging workflow (YMMV!)
Before I start the work, I:
Keep a document open as I'm working. I use Obsidian, but any text file will do
Use the questions above to help me create a rough foundation for the project
As I'm working, I:
Collect the links I find to help me
Write down my steps as bullet points
Not sentences!
Maybe grouped by something that helps me organize my work process and thoughts, but only when that's helpful and not a distraction
Keep track of my questions and their answers, as well as lightbulb moments.
Identify choices I make and how I make them
When I've met my goals for a project/course
First pass
Start making headers for my groups of bullet points and seeing what flows best
Turn the bullet points into sentences
Not optimizing for readability or style yet, just:
Correctness
Completeness
If the project involved code, I create gists of any code I want to include. I used to just take screenshots, but I realized that's annoying for anyone who might like to be able to copy and paste the code, and worse, it's completely inaccessible to low-vision or blind readers.
Second pass
Change my font! It sounds silly, but changing the font can help you read with fresher eyes and catch typos
Run my text through a grammar and style checker
Use text-to-speech (TTS) software like Natural Reader to have my prose read to me. I often find spots where what I've written is either too terse or too wordy, or just makes less sense when read aloud than it did in my head.
Third pass
Move my content to my blogging platform (Hashnode)
Add images and alt texts
Make sure my links work
Add a subtitle
Add a few tags
Publish!
I always have to remind myself that I can edit posts after I publish them, and to not the perfect be the enemy of the good. Just hit publish!
Then I'll post the link to Twitter, Mastodon, Polywork, and maybe LinkedIn
And add the link to my personal site
I hope this will help you blog your projects!
Places you can find me: