Code Newbie Challenge 2018
I just joined Saron Yitbarek’s 2018 Code Newbie Challenge, and for my challenge I chose to blog more. #cnc2018
If you would like to join, sign up here and you’ll get an email with these instructions (along with a few more details):
PRE-MISSION: Read 3 tech blog posts you wish you wrote. Jot down why you like them and what you'd change. GOAL: Find examples of good tech writing to see what you'd like to incorporate into your own posts, and what you might want to avoid. You'll refer back to these later in your challenge.
Saron says that most tech posts fall into three categories: tutorial, explainer or project. The goal for challenge participants is to read through a blog post in each subject and reflect on three things we liked and three we didn’t. Below are three Medium articles I felt were interesting.
Tutorial
This post is a super short Free Code Camp tutorial that walks you through the process for creating a static blog. This is a nice process because it involves no programming and is free. Aravind suggests using this process for a portfolio or blog and in the tutorial he outlines the steps for creating a blog.
What I Liked
I liked how clearly it was written, with each step clearly delineated. I also appreciated that shell commands were written out and separated from the rest of the text. The post was nice and concise, without a ton of extraneous fluff or documentation. Each service or framework (eg. Hugo, Firebase, Node.js) needed for this project was quickly described.
What I Would do Differently
There were a handful of issues I had with the post. Although I like not being pointed to the documentation at the beginning of posts, a list of handy links are always nice at the end. I also would have liked to see a example of the site that was created for this tutorial and maybe even some code on GitHub. Finally, it would be useful for some users to provide a some common troubleshooting problems and their solutions. None of these issues were dealbreakers and omitting them made for a short read, which I really appreciate.
Explainer
In this BaseCS post, Vaidehi makes a great point: “Binary is something that few programmers think about these days. Deep down, we know that it’s important and worth learning about, yet can seem so overwhelming and kind of unnecessary to think about.” That’s been my experience with binary. I’ve read about it before and felt like I understood it, but it’s not something that I ever make use of and has mostly been forgotten.
What I Liked
My favorite part of this post was actually the hand-written (drawn?) explanations. Somehow those images made the article much more compelling. I also particularly enjoyed the section describing how computers read binary, although it would have been nice to have more information about how compilers work. I loved the resources section at the end of this article. I think almost every post should include some kind of a resources or links section at the end.
What I Would do Differently
I had very few complaints about this post. In some places it was confusing, but those weren’t terrible. It was a pretty long article and it might’ve been possible to get the information across in fewer words. I would also like more examples of how knowing binary might be useful for programmers.
Project
This was a post on the Chingu Medium blog written by an experienced mid-level programmer who challenged himself to write an iOS and Android app in a week. It’s a fascinating story and really interesting to consider what’s possible with limited time.
What I Liked
I really enjoyed reading this post. It was written in an engaging and humorous style that made me feel like I was part of his adventure. Including motivational quotes was kind of a nice touch and almost reminded me of the pull quotes used in magazine articles, which act as brief breaks to keep the reader engaged. I also liked the countdown format he used, starting at 168 hours and going down to zero by the end of the week.
What I Would do Differently
I only noticed a few things that didn’t sit well with me. First, the screenshot at the top of the page seems too large and doesn’t feel like a good lead-in to the article. There were some typos and grammatical errors throughout the text, but I don’t think Anton’s first language is English, so I can’t really fault him there. Overall the writing was quite good. I found myself wondering about the actual details of his project. How many hours did he devote each day? Which day is he on during a specific moment in the countdown? It would have been nice to get a bit more detail, but I also really liked the way he put everything together concisely.
Takeaways
Doing this review was more work than I thought it would be, but it was also incredibly useful. I discovered some great methods for engaging the reader — making jokes, including quotes, and creating an engaging story. I didn’t mention this, but I also really like funny gifs sprinkled throughout the text (although this can be overdone). The things that I liked and will probably include in my own writing are (1) clear and concise instructions, (2) humor and good storytelling, and (3) including resources at the ends of posts. Things that I will try to avoid: (1) using a long-winded or folksy writing style, (2) not including concrete examples, and (3) not thinking about details or questions the reader might have or not addressing them in the post.
Originally published at danstrong.tech.
