Monday, January 22, 2018

The Code Newbie Challenge for 2018 #CNC2018: BLOG MORE: Introduction

Hello to new readers that are coming across this blog for the first time. To those who have read these pages for a while now, this should not surprise any of you at all ;).

I've decided to take on the Code Newbie Challenge for 2018. There are four "tracks" that you can choose. They are:

Start Coding
Code More
Blog More
Get a Job

I have chosen the "Blog More" challenge for a specific reason. Much of the time on this blog I have talked about testing and peripheral topics from a layman's point of view. I've strived to "speak dude" as often as possible, and to that end, I've kept coding specific stuff to a minimum. that sounds like a simple answer, doesn't it? Well, let's get real here. There's a darker secret. Part of the reason why I don't post code frequently is that I harbor a fear that people will look at my code and think it's simplistic, stupid or just plain lame. To tell the truth, that may happen. Maybe it won't. Regardless, I've always been a little leery of posting code samples beyond language tutorials because I've just been concerned about getting it picked apart.

That's the overwhelming reason why I chose this challenge. I can't get better if I don't actually put something out there, right? I can talk a mean game about what I know about things like automation and web development, but does it really matter if my actual code is lacking? More to the point, wouldn't it make a lot of sense to actually talk about code, show examples, explain it from my perspective and let people who do know about code comment on it?

Sure, it might bruise my fragile ego but isn't that the whole point? How do I expect to learn or actually demonstrate I know anything if I'm not willing to show what I actually know and take the chance that someone might be willing to tell me a better way to do it? On top of that, there may be lots of things I may be doing that are actually interesting and may be helpful to others. Finally, if I can explain what I'm doing in a blog post or several, I can explain it to anyone and draw on it when I write code in the future.

Let's get this party started. Each assignment as part of this challenge will be posted here. This is my own preamble to get the ball rolling. Look for the tags CNC2018 and CodeNewbieChallenge to see posts specifically targeted for this challenge.

Exercise Zero: The Pre Mission

Read 3 tech blog posts you wish you wrote. Jot down why you like them and what you'd change.

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.

There are three styles that were described for this challenge. First is the "Tutorial", which actually walks through how to do something. Second is the "Explainer", which take a concept and breaks it down. Third is the "Project" which describes how to do something and gives actual examples that you can follow along and build yourself. The pre-challenge is to pick three examples, (one from each category) that I wish I had written, describe what I like about it, and what I would like to see to improve the piece.

Tutorial: "Protractor for Beginners, Part 1" by Hannah Pretswell

Why a tutorial on Protractor? Because it's what we are exploring as a replacement for our current automation framework. Nothing like a pressing business need to get your mind racing and your thoughts flowing. Hey, you know it will come in handy very soon, right? For starters, let me comment on something I really appreciate. Hannah said she struggled with getting the pieces to work together. Hearing that up front helps me in two ways. First, it lets me know that the tasks ahead may be challenging. Second, she also lets me know that she's done her best to document those frustrations and help let me know that I likely will succeed if I'm patient and follow her advice. Too often, I've gon through tutorials that expect a user to jump in and get moving with little concern over the sticking points. Gladly, that's not the case here.

Another positive is the fact that there are a fair number of repetitive steps. It's tempting to spell them all out, but by doing so, it makes updating a tutorial daunting and thus something the writer would likely not do. Instead, she points to a few additional tutorials already written that explain the process of setting up your environment and making sure everything is working correctly before getting started. Additionally, the resources listed point to the protractor GitHub page. This is a good practice because it lets the user get started with the most recent advice from the maintainer of the framework so that if the instructions change, the writer of the tutorial doesn't have to be the one to change the details on her site as well.

So, what would I have done differently? Truthfully, not much. I think it's a solid opener and it goes through the specifics as the first part of a tutorial should. I suppose I would have liked to have seen some example output of the code as displayed and some output of tests as well. For me, with a variety of tutorials, I think this is a good step so as to show what you could expect. I understand why many people don't in that OS changes and formatting details could put images like that out of date quickly, and it does add overhead to downloading what would in many cases be pictures to demonstrate the output. Still, on the whole, this is a really solid example.

Explainer: Test Driven Development in BASH by Torstein Krause Johansen

This is presented as a talk, but in many ways, that's a great way to explain a concept in a few words, with the impetus on the reader to go and learn more if they are so inclined. Specifically, I like the curt and focused content, the way the information is presented and the walkthrough of the ideas with examples. Each slide builds on the previous one and lets you see why the topic makes sense and the reasoning behind Torstein's approach. I was also excited to learn about shunit2 and I must say I'm more than a little curious at this point.

So what would I do differently? Again this is a set of slides from a talk, and at first glance, I'm guessing the HTML code was put there for a reason, but if the point was to demonstrate bash syntax and how it interacts with a testing framework, the HTML was distracting and made the underlying code hard to read. Again, I may be missing a key context here as to why that was presented that way (perhaps to prevent copying and pasting willy-nilly) but if that were the concern, I could see saving screenshots of the code itself and displaying pictures (great to prevent copy and paste but admittedly a nightmare to update and keep current).

Project: 10 Angular and TypeScript Projects to Take You From Zero to Hero by Dan Wahlin

This interested me seeing as I will be doing work with Protractor and Jasime as a testing framework for Angular apps. To that end, it helps to have something to look at, play with and practice on and these ten projects will allow me to do that. I like that the projects start simple and get progressively more difficult as they go. Each project is laid out with sample images of what you will build with links to each of the projects so that the project page is independent of each of the individual listed projects. The projects are lust listed with a title, a basic description, level of difficulty, a link to the files and some pictures of what the project will look like when completed.

On the whole, this is a nice layout and method. It leaves it up to the individual reader to decide where to expend their energy and each project simply links to the necessary packages to get them done. Were I to do it myself, I would probably split each project out to its own page and try to give some instructions about what to do with each. Having said that, the economy of having ten projects to choose from without a lot of navigation and page dancing is a good tradeoff.

There's the start. The assignments proper start on January 22, which is the same day this post goes live. Feel free to follow along and, as I tackle each assignment, your feedback and commentary is appreciated :).

1 comment:

Mark said...

I just thought I'd add a note of encouragement regarding your decision to post more code.

Haters gonna hate, as they say. So do it anyway. Especially if you're as frank about your code as you were in this post about the thought of posting your code. If you're upfront about your code not being perfect, and you're open about accepting constructive feedback, anyone commenting in a way that is not constructive will look like a fool to everyone else.