Write a terrific Hello World

Back in 1974, Brian Kernighan wrote the first documented “Hello World” example. It was an introductory exercise for the C Programming Language, distributed as an internal memo for other engineers in Bell Labs. This allowed his colleagues to get their feet wet with writing their first C Program back when computers were room-sized, and they limited time working on these machines.

A few years later in 1978, he published a book with Dennis Ritchie titled, “The C Programming Language,” which began with the Hello World example. This illustrated the minimal working program one could write to understand the workflow and syntax to get started in C. Hello World then became the de facto standard as an introduction to any computer language.

Today, if you want to introduce a programing language, scripting language, API, or library, you will need a rock-solid Hello World example for prospective users to gain confidence with your product. Hello World has become the trivial exercise to quickly show basic syntax and workflow for a new programming language, tool, or API.

Unfortunately, when it comes to writing a Hello World example, programmers mistake how long you spend doing the exercise with how long they should spend writing it.

Creating A Compelling Hello World Example

The most important thing needed for a good Hello World example is to not forget it.

Don’t orphan your Hello World example!

Programmers read and use Hello World examples often as they learn new skills. When it’s our turn to write documentation, it’s easy to assume that we write this example once and leave it behind as we dive into more interesting details to write about, a set it and forget it attitude.

I would suggest that you should revisit your Hello World example regularly, testing with a fresh audience to see their interpretation of the example. Look for opportunities to watch a brand new user try your example. As you watch their efforts trying your Hello World example, you need to ask yourself questions like:

  • Can they navigate the example without outside prompting?
  • Do they have to Google something in order to make it work?
  • Do you find it necessary to explain your intention once they have completed the example?
  • Are they excited to try more?

Watching a variety of users with different skill sets navigate your Hello World example (without hovering and interfering) will tell you so much about how successful that example is, provided you put in the time observing their reactions. Be sure to have a constructive conversation once they finish to find out what worked for them, and where they felt stuck.

Return to your work with fresh eyes

Self-editing your own written work has the best results when you can view it with detachment. Time away from your creative efforts is one of the best tools to view it with fresh eyes, and only then are you able to make the edits necessary to take your work from good to great.

Returning to try your own Hello World example a week or a month later (after watching other users try it out) will allow you the perspective to remove verbose passages and add in necessary information to help future users get through this first important step. This time away from your work will allow you to more quickly decide what should remain, and what needs enhancement.

Hello World can help you convert more sales leads

A welcoming Hello World example will take a cold sales lead and warm them up giving you the opportunity to turn them into a customer.

Having information readily available that make users feel empowered to dive in deeper to whatever your technology is will warm them up to your product by the time they talk to you. Saying you have the best in class API documentation will really only be useful if you can prove it, and Hello World can help build that trust.

Give your potential user a taste of what’s to come.

Article photo by KOBU Agency on Unsplash

Streamlining training to benefit the student

In a previous job working for a banner ad company, I held two different job positions over the 4+ years I worked for them. For the first couple of years, I worked in their production department creating custom ads for big corporations. I then transitioned over to their support team to train new clients and support efforts from their in-house design teams.

When I began training for the support team, I shadowed various colleagues. I watched how they conducted trainings, what resources they had to share with the people they were training, and how to support them once they started making their own ads.

The first training I sat in hit me like a deer caught in the headlights. It was a live hour long screen share showing techniques I was very familiar with having worked with these tools for quite a while. By the time we finished the session, I was numb. So much information was jammed into that one hour.

This left me with the question, if I felt lost after that training with all of my previous experience, how did the new client feel?

I learned that after the initial training, there was quite a lot of custom support offered, making for a time intensive experience for both the client and our support staff. To top it off, there was very little written help to support client efforts. The help files we had were the bare minimum, and there was no way to add onto them.

As I started to prepare for my first training, I put myself into the shoes of the student. I wanted to create a more relaxed training that left the client feeling equipped to start their project and not worry about the technical stuff. I wanted to leave them with enough structure to drop in their initial creative assets after we completed the initial training.

  1. I created a quick survey to find out what structure of project they would need to build, and what types of media they would be using.
  2. I built bare-bones versions of the projects with obvious sample assets to get them started. These projects were well organized and commented in the HTML, CSS, and JavaScript.
  3. Using Evernote along with Skitch, I created easy to ready directions with all the notes for topics we would cover in the training session. This way the client wouldn’t need to take excessive notes and could watch to get a feel for the setup. This allowed me to publish a document and easily send a link to anyone in attendance with annotated screenshots and zipped files of their skeleton projects.
  4. I recorded the screen share and sent a link with a followup email once the session was over.

Approaching new clients with a structured training with so much bonus material left me feeling more confident and relaxed as I conducted my sessions, and made my students feel more confident in what they were doing.

As I supported client requests, I found that I would often answer the same questions multiple times. Some of my colleagues would have draft emails with answers they could send over, but often they would type the same responses repeatedly.

Still unable to update our help files, I kept an Evernote notebook filled with my own answers with files I could quickly share with our clients. I would offer a quick overview in a response email and a link to my more detailed document. I could send this out with little trouble and say something like, “here is the quick response, give it a read. If you need more info, we can schedule a call.” Sometimes I would need to hop on with the client, but more often they would read what I sent over and solve the issue themselves.

When a client feels supported, they become your best salesperson. Designers and programmers that I worked with would switch companies, and advocate to work with us for our dedicated support. When I did finally leave that job, my entire team was using documents and files I wrote and created, and techniques for teaching that I established as best practices there.

Useful Sublime Packages

Sublime Text on its own is a great tool to use for HTML / CSS / JavaScript development — but it gets even better with packages! Sublime Text is free to evaluate, with a nominal cost for continued use — a great way to get your feet wet with the tool.

Installing Package Control into Sublime allows you to include add-ons to make coding easier. Once you have installed Package Control into Sublime text, the next step is to locate packages that are helpful. I find a lot of benefit with the following packages.

Bracket Highlighter
Opening and closing brackets/braces/parenthesis can be tricky to keep track of — especially if you are troubleshooting code. This package will highlight the complementary bracket/brace/parenthesis your cursor is currently on.

Sublime Code Intelligence
Many IDE’s (Integrated Development Environments — tools to write your code in) offer code completion. Sublime will do this for repeated statements, and it will do it pretty well, but not for code not previously entered. Sublime Code Intelligence will help with code completion for common HTML, CSS, and JavaScript syntax — helping you to avoid typos.

Sublime Server
Sometimes supporting libraries you might include in your project (for example if you are including a framework like jQuery or something similar) don’t run well in a local environment (testing files directly from your computer). Making your local development environment more like a web server can help avoid some of these issues.

There are many local testing servers you can download, but Sublime Server is nice since you have everything integrated together and you can run any open file by right-clicking on it and choosing ‘View in Sublime Server’ which will launch your file to your default browser in the localhost.

In the examples and demo’s to come, I tend to utilize all of these packages to aid in my development.

Hello World is merely the start

When learning a new computer language, quite often the first example is to create a “Hello, World” type application. “Hello, World” is something we tend to take for granted now, but it wasn’t always the defacto starter example.

Learning a new computer language can be daunting. There are new ways to do things, many details as to how to organize and define your code, ways to package up your code, then to deploy your code to where it needs to go in order to function.

“Hello, World” was first used in an internal memorandum for Bell Labs back in 1974 by┬áBrian Kernighan, and later widely released in his book for the “C Programming Langage” published in 1978. At this time computers were still typically large office machines taking up quite a lot of space, nothing like we have today.┬áBrian Kernighan used this “Hello, World” example as a way to quickly show the basics of program structure and workflow, to get the programmer’s feet wet, and feel like they accomplished something.

So, “Hello, World” is a great start, but the story can’t end there. Learning a new language means you have to buy into its story, how it’s useful for you, what it can do for you, and how it can enable you to help others. When we learn any new language, a big reason why we learn is to help others. To help them communicate, to enable them to do less work, to make things easier.

After this great introduction, we need to keep things moving – and the best way to facilitate this is through story coupled with technical details. So often when learning a new language or API (Application Programming Interface) you are presented with dry stale details. Without a compelling reason to continue past “Hello, World”, a user learning will only do the bare minimum to get by.

If someone is learning your language or API, don’t you want them to dive in deeper. For them to advocate using your product rather than someone else’s? Creating documentation that is compelling, that tells a story, to get your users not only interested, but advocate for it’s usage to their peers – shouldn’t that be your goal?

Story is important.

What are you saying after “Hello, World”?