Designing a Good 'Hello World'

Hello world

Our most popular consulting service is our friction audit (aka friction logging), where we evaluate the Developer Journey using the clients' website and product. The ultimate goal is to build a hello world proof of concept (PoC) using the solution and technical information provided.

The term hello world originates from the programming world, where developers start learning a new programming language or framework by building a simple proof of concept (PoC) that outputs the words: "hello world". By accomplishing this, developers verify that the language or framework is correctly installed and functional, and that they have a basic understanding of it.

Today "hello world" applies to more than just programming. It can comprise any steps which take a new user from scratch to a minimal working PoC, in a short amount of time. It also serves as the foundation for your Quickstart guide.

It's imperative that you offer developers a 'hello world' exercise, AND that it is a good hello world. Let's take a quick look at some key considerations for designing a hello world that best represents your product and support your developer's journey.

Initial Planning

As with your website's design or technical documentation, planning your hello world requires time, effort, and thought.

Start by asking: What is the simplest task or goal that a developer can accomplish with your solution to prove they can get it working?

For example, if your solution has a REST API, your hello world could involve sending a request to an endpoint and getting a success message back to prove out the two-way communication. If your solution includes a cloud-based dashboard, you might augment this by having the developer enter data by hand, and then programmatically retrieve it to prove out the cloud-API integration. And if your solution involves out-of-band verification, your hello world might involve the successful receipt of an SMS message (e.g., "hello world") on the developer's smartphone.

Factor in Prior Knowledge (or the Lack Thereof)

Many Quickstarts falsely assume the developer has prior domain expertise (e.g., expertise in databases, cloud services, etc.). For example, if you offer a database-centric solution for analytics, you might assume your developer audience consists of experienced database developers. In practice, however, your audience may comprise business folks who are interested in analytics or new developers with only elementary technical skills or knowledge.

The best approach is to first segment your potential audience and identify target personas before planning your hello world and quickstart. Identifying the potential skillsets of your audience beforehand, allows you to focus your content accordingly, while figuring out how to accommodate various knowledge levels. You can then configure your Quickstart to communicate any required domain knowledge up front, and, ideally, signpost readers to additional resources before they even begin.

Identify Prerequisites and Dependencies

Most solutions today comprise an intricate chain of dependencies that require an equally intricate installation and configuration process.

When designing your hello world, identify the minimal steps and prerequisites required to get your solution up and running. This could involve account signups, downloading and installing packages, compiling libraries, making REST calls, opening firewall ports, authenticating, etc. Remember that developers are likely new to your solution and may not have these things set up. Assume your audience is starting from scratch and provide a list of prerequisites and dependencies like packages, external database systems/accounts needed, etc.

Complex chains of dependencies can quickly cause friction, especially when they plunge the developer into a quagmire of build problems and compile errors. Help the reader by putting together a comprehensive troubleshooting page of common problems/error messages and how to resolve them. This helps developers get up and running faster and shows that you have their success in mind.

For really complex installations which make your Quickstart anything but quick, consider pre-creating an environment for the developer to use. This could include pre-populated sample databases, pre-provisioned Docker containers or VMs, publicly-accessible demo cloud service accounts, etc. Or, take things a step further and create a fully-functional fake environment. A great example is the console window embedded in MongoDB's technical documentation that allows developers to immediately try out commands without any installation steps.

Augment with Tutorials

Your hello world and Quickstart must be focused on getting the developer up and running as simply and as quickly as possible. They are not be-all-end-all resources to showcase all of your solution's functionality. That is where a set of tutorials come in.

As with the Quickstart, each tutorial requires careful design. Identify the key use cases and functionality you want to showcase and how they build off of the Quickstart, and, optionally, each other. Keep each tutorial as simple and focused as possible because the developer is still new to your solution.

Aim to create a handful of tutorials that accommodate your target personas, and you'll help developers take things to the next level.

Trial Period Considerations

Lastly, ensure you offer a free tier or a trial period. Developers will appreciate the ability to evaluate your solution for free. Keep in mind that developers are busy and are likely evaluating your solution amongst those from competitors over several weeks. Ensure your trial period provides adequate evaluation time – a good rule of thumb is 30 days – with the flexibility to prolong it, should a developer request additional evaluation time. And ensure the trial provides all of the resources and functionality necessary to complete your hello world without having to upgrade to a paid tier.

Say Hello to Your World

A well-designed hello world allows you to say hello to your world of developers. It provides them with a welcoming experience, helps them on their journey of evaluating your solution, and shows you've thought about their success.

If you need help determining a good hello world for your developers, reach out so we can help you with our DevRel expertise.