Make It Dead Simple: Documentation

Lately I’ve been writing a lot of documentation, instructions, and guides for work, Hackster.io, and my side-project (Open Smart Hub). Most of the time the instructions needed to be compiled from multiple sources but kept simple and digestible. As a long time consumer of documentation, I’ve come to a couple realizations about instructions and guides. The most important is:

Make it dead simple. It should be fool-proof and easy to follow.

Don’t make assumptions about a reader’s skill level, the more knowledgable readers will skim over the instructions they already know, but newcomers will treasure those details.

How?

  1. Draw up a storyboard of the steps. Just like primary school, where they would tell you to brainstorm on a sheet of paper before writing an essay. This will help you figure out if there are any missing parts before you get into the nitty gritty details, whether or not the ordering makes sense, and if you need more research as well.
  2. Start with a schematic of the parts (if it’s a hardware related or multiple component documentation)
  3. Add pictures (these always help clarify for the unsure)
  4. Be concise. Make sure that each word added to your documentation adds value.
  5. Don’t overwhelm your reader. (Avoid using acronyms unless you have elaborated on them earlier in the documentation)

Making this kind of robust yet straightforward documentation takes time, but it will also reduce the amount of support and questions you might receive about it in the future.

NVM – Your Node.js Friend

I’ve been doing a lot of development on an old Node.js version lately (v0.10.28) and after realizing this, tried to update my Node version only to find out that a bunch of my previous code no longer worked due to base changes since my initial download of Node.js.

After some minor digging into hosting multiple Node.js versions but being able to switch between them whenever I wanted, I came across NVM (Node Version Manager). The NVM created by Creationix supports Mac and Ubuntu users, but for Windows users there are alternatives (nvm-windows and nvmw)

The basic gist of using it is to install NVM and call “nvm install 0.10.28” or whichever version you want to install. Then you can now call “nvm use 0.10.28” from your shell window and you are using that version! It makes it super simple to switch between versions of node and also check your development compatibility across the different versions and better inform your users.

Not Just Another Code Monkey

Today my coworker (and mentor) mentioned something to me that really stuck in my mind.

I’ve done this kind of work plenty of times. Let’s work together on it. But you making a name for yourself is more important to me than any amount of visibility I would get by leading it.

In my mind this immediately evoked a scene I’ve experienced many times in MMORPGs (Massive Multiplayer Online Role Playing Games) where the higher level player helps a friend gain experience and finish their quest in order to level them up and get them closer to being on the same playing field. The ultimate goal by doing this is that they can both work together, have fun, and accomplish bigger goals. Needless to say, my mentor has been a great help in nurturing my growth and getting me excited to arrive at work every morning. I think that this mentality is the sign of a great mentor/manager and I aspire to do the same when my time comes.

“Not just another code monkey”

It’s been in the back of my mind since the first day I began to code. Almost anyone can learn to code and pick up basic programming skills from the internet, tutorials, and online courses. The telltale sign of a good programmer/engineer is not just how well they can write code, but also how they think, how they interact with others, how they problem solve, and how they learn.

Today I feel like I’ve been given the chance to showcase my skills and become the person that drives change and features!

Twitter, Another Social Network?

I honestly never really bought into the idea of using Twitter until recently. While I was attending events I would always hear the sponsors saying “tweet at us” but that never really made me want to join another social network. This weekend changed how I thought about it.

 

It’s cool for companies, but why do I care? That was my main question before this weekend.

“Facebook is for friends, Instagram is for posting photos of your life, LinkedIn is for resumes and professional connections, but Twitter is a social space for professionals”.

I paraphrased what a work friend said, but the message still rings true.

  1. Twitter is becoming the social space for people and companies with similar interests to interact with each other and grow off those ideas.
  2. It’s a fast paced social interaction with more and more companies responding faster to customers and developers through Twitter than email.
  3. Twitter can even help you gain that connection through email or phone if you don’t have one already!
  4. It could help propel your reputation in the particular space you are working in. (for me that would be Internet of Things)
  5. It allows you to track trends that you might be interested in with hashtags.
  6. The 140 character limit helps you learn to be succinct

Why do companies care? Companies are using Twitter to gauge the publicity of certain ads or campaigns as well as how engaged their audiences are with their products. This works really well for startups trying to create publicity around themselves and their products because of how social and easily re-tweetable conversations are.

Tips:

  • Since it can be used as a professional social space and everything on the internet sticks, I would suggest not posting your every thought. No one cares that you made a really good sandwich (unless you’re a chef trying to promote yourself) and you don’t want to hurt your reputation with unprofessional tweets about last night.
  • Follow companies and people that are doing things that you are interested in.
  • Stay active and retweet interesting conversations and post some of your own!

 

Other side of the Interviewing Loop (The Interviewer)

By the time we get to this point in our careers, most people have participated in plenty of interviews as the candidate. We know what it’s like to be interviewed, but do you really know how to do the interviewing? If you think back, do you know what made an interview horrible and soured the idea of working at a company? The key to being a great interviewer is to treat the candidate like a customer. You want to make sure that they leave loving your company even if they didn’t get the job.

Some helpful tips I’ve received for interviewing in the Software Space:

  • Ask about problems that you or your teammates had to code and solve. This allows you to fully understand the problem you are posing, how you would solve it, and understand their thought process/tradeoffs and maybe even get new ideas on how it could have been solved.
  • Classify them and your team (these don’t have to be mutually exclusive, but most people tend to be stronger in one):
    • System Dev: Developers more adept at creating the system and building blocks for others to use. They can understand their users/developers and the possible scenarios in order to build an elegant structure that supports the correct usage.
    • App Dev: Developers that are able to use existing APIs and take the building blocks given to them to solve a problem and build a robust solution.
  • The candidate should be flexible. It’s great if someone is a master at one thing and one language, but this is a fast paced development space. You need to be able to enhance your skills and learn on the fly.
  • Analyze the candidate with respect to the job that they will have within your team in the near future and what your daily interaction will be like with them, but also keep a broader idea of whether the person would be a great hire for the company.

Diving into AngularJS

I’ve heard the name “AngularJS” get dropped here and there for a long time now, so I figured that it was time I delved into it a little to see what the fuss is all about.

Why AngularJS?

  1. They do a good job of making it easy to develop a website in the typical MVC (model, view, controller) fashion.
  2. Re-usability / no-repetitiveness of code with directives for elements, attributes, and class names and ng-repeat
  3. Easy to use filters on objects/data.

Here are some of what I learned from my quick dive into the world of AngularJS:

  • Within a controller, it is always better to create a reference to “this”
  • No need to pull in all the separate javascript files anymore. Bootstrap, JQuery, etc. is all included.
  • create an angular module for every “app”, website, or object based on functionality.
  • add controllers to the app for all reusable functionality / better modeling.
  • using the “ng-{keyword}” tag in your html objects gives you a massive amount of flexibility in showing, hiding, repeating, HTML elements based on JSON data, and 2-way data binding.
  • === is a comparison similar to ==
  • ng-class=”{className:variable === 3}” setting of a class based on a variable
  • INCREDIBLY EASY to use JSON data
  • forms have validity BUILT IN and allow you to toggle things based on the value
  • CSS formatting for input types:
  • Include html templates/files in other pages with:
  • Has services built in:
    • $http for fetching JSON data
    • $log for login messages to the javscript console
    • $filter for filtering an array
    • Example:

Would I use it regularly?

I believe that I have found my replacement for jquery and a good model for javascript development for the web. I definitely will be using it for most (if not all) of my websites.

Resources:

 

Updated Experience with Spark Core

After a week of continual use with the Spark Core I have an updated view on the Spark ecosystem.

It’s incredible how easy it is to develop and connect your core to sites developed in Node.js (check out the project I made: http://sparkrgb.azurewebsites.net/). The biggest part of that project was making sure the RGB strip worked and the UI for the website interface. Connecting the two together was the simplest part. The only major disadvantage to using the Spark ecosystem is the fact that you are required to use their Spark cloud to communicate to your device. (Although they are open sourcing a spark-server on Github, it uses the same format as the Spark Cloud.)

Here are some of my personal remarks on the ecosystem:

  • Connecting the Spark to a Mac is pretty easy through USB, but doing it on your Windows machine requires a little more driver interaction. See my blog post on that here.
  • Resetting your Spark’s preferred WiFi connection with the mobile apps is horrible when you compare it to the simplicity of using the command-line interface on your development machine through USB.
  • The Spark Core remembers 7 WiFi credentials. If you add an 8th it will remove the 1st.
  • In order to compile an INO into the firmware, an internet connection is needed on your development machine at least, so there is no way to develop on a self-contained network even if you do not plan to use internet connected capabilities.

Overall, I think that the Spark ecosystem provides the best experience for developing IoT devices currently.