My Metric for What Makes for Great Documentation

Everyone is different. So I can only speak for myself when I describe key factors that make for great documentation on today’s modern developer platform sites.

It is imperative to remind one another that assumptions are inevitably made when writing for an entire ecosystem of developers, considering that the spectrum ranges from newbie to seasoned. On the developer’s side of things, researching a technology, regardless of the intended purpose, takes time.

When docs for tools are designed with a vast array of users in mind, it makes for a more inclusive, productive experience on their sites. No piece of documentation is perfect, but some cater to more of the ecosystem than others, whether it be intentional or not.

When I decided to deploy my first web application, which was an assignment while attending the Resilient Coders bootcamp, I began exploring a recommended platform, Heroku, that is designed to handle the deployment process without too much grunt work on the developer’s end.

I found the process to be relatively straightforward, memorable, and easy enough for me to want to come back to in order to utilize it as a PaaS for future web apps. Just based off of my experiences researching different tools as curiosity consumed me, here’s what currently stands out to me as a basic, quick checklist for what makes for decent docs:

1. Easily navigable

2. Offers sequential steps to reach specific, clear goals as a result of explicit input instructions

3. Offers occasional visual aid, whether it be in the form of code blocks, screenshots, or links to what your intended output should resemble when reading steps

4. Embeds introductory learning 'back tracks' throughout docs for users who are stumped on more programmatic or architectural concepts as opposed to operational objectives specific to that tool

5. Provides links around pieces of important information that may lead to even more insightful information

6. Reads in an abstracted way, progressively building more complex concepts on top of the basics of the tool

7. Inclusive to beginners: points beginners in a direction to get acquainted with concepts behind information in the docs

BONUS**

8. Provides opportunities to run code in a built-in virtual IDE

Below, I describe different personas for potential doc readers and how amazing documentation for a language and/or tool is impactful in their respective scenarios…

Different Angles to Approach the Needs of Developers Exploring Docs

Maybe your reason for snooping around docs falls into one of these categories:

You’re interested in learning about a specific language or tool to potentially leverage it to build something…

In this particular scenario, definitions of words scattered throughout the docs are very important so that you can learn about platform-specific terminology, and purposes behind certain operations that are both optional and required when building something.

Service workers are referred to as dynos in Heroku, to manage resources for your app to scale up or down, depending upon unpredictable traffic and usage on your web application. In Docker, they are referenced as containers with instances of your application that can join swarms with a swarm manager. Clear definitions of such terminology are necessary to provide you with the context needed to successfully learn about the tool, experiment with it, and potentially utilize it to create something.

You’re new to coding entirely…

You might be feeling a variety of things if this is your case. Overwhelmed, nervous, confident, excited, or intrigued? Regardless, in order to help you accomplish a task with a tool you’re completely unfamiliar with, the documentation should be able to cater to users new to the ecosystem.

Not all docs are going to be beginner-friendly, and not every doc should be designed that way, as it depends on the complexity of the problem you are solving and the tool that is needed to provide the solutions.

Without insulting your intelligence, if you’re new to programming and would like to learn Rust, you might need to learn what a print statement is, in general, before you learn what macros are in the context of Rust. You might need an explanation about garbage collection before you delve into how Rust handles (or, in this case, doesn’t handle) that operation. A well-written doc that is beginner-friendly will be careful about introducing theoretical concepts prior to or while diving into how they are implemented in that language.

You need to learn something new for your job…

Building side projects is entirely your choice, if you have the free time to do so and, thus, make the time. However, a project assigned to you at work is not.

It’s common for teams to be introduced to newer or more practical technologies for what is to be built or refactored. Tackling the transition is one aspect of this scenario. The other is the approachability of the resources available to you (primarily online in our internet-driven times) that will facilitate your learning process, which you cannot control, being that you are the reader/user and not the writer of these docs.

In this scenario, docs should be straightforward because this can ease the implementation process in an existing codebase you’ve been working in. If there are sections of the docs that offer solutions for migrating from a different technology to theirs, that’s even more impressive!

5 Examples of Awesome Documentation for Devs

1. Rust

Rust is a low level programming language with some buzz around its capabilities and potentiality. Rust has been increasingly garnering attention, especially in circles where there’s excitement around Web Assembly complementing JavaScript for porting software to the web.

The Rust Docs is probably my absolute favorite resource for learning more about Rust!

Why are Rust Docs Great?

• Easily navigable

• Beginner friendly for new programmers and/or new low level language programmers

• The site offers both project-based learning docs and traditionally structured documentation

• Implements embedded code blocks throughout segments of chapters that are interactive, compilable, and editable.

Which reminds me: be on the lookout for my next article where I list awesome podcasts to listen to if you’re interested in tuning into conversations about Software Engineering, Web Dev, Data Science, or groundbreaking Math & Science topics.

2. Docker

Let’s acknowledge the fact that Docker’s practical usage guide has Night Mode toggling functionality. We’re already getting off to an amazing start here. Beyond the mode toggling…

Why Are Docker’s Dev Docs Great?

• Recap & Cheat Sheet sections available at the bottom of each chapter in the docs, which is important because it helps the user reinforce concepts and keywords referencing the concepts that may have slipped the mind during experimentation with setting up their environment.

• Links are spread out across the docs which make it easier to gain insight into the information they intend to expound upon

• Allows for backtracking before proceeding into more complex explanations of the concepts they're highlighting, which is beginner or "refresher" friendly.

3. AWS Amplify

If you need a quick refresher, AWS Amplify is a cloud service for developers who may need certain aspects of their application and code handled seamlessly. This could include the backend, authentication, database management, and deployment processes.

What Makes AWS Amplify Great?

• In the JavaScript Amplify section, there are framework-specific links that highlight very popular JS frameworks. This is great for framework-specific details for integrating AWS configurations into the frontend.

4. Digital Ocean

Something to note about Digital Ocean, something that is made clear consistently throughout the platform’s site, is that this cloud infrastructure service is adamant about everything they have being made with developers in mind. That is crucial!

What Makes Digital Ocean Docs Great?

• Comprehensive separation of API Tutorials, Metadata Guides, and OAuth implementations for your application.

• Side by side API notes and programming examples with an IDE-inspired background and font in relevant languages which gives developers more insight into how certain processes could be constructed in order to perform actions.

5. Heroku

The Heroku Dev Center really has a gorgeous documentation setup. Heroku is known for its powerful, easy deployment services for developers. There are a few things worth noting about the site.

What Makes Heroku Docs Great?

• Provides sequential instructions for handling different programming languages and their respective packages that are critical to running tasks, service workers, result store, and message brokering systems.

• Docs provide resources about other relevant tools that go hand-in-hand with Heroku such as Git for your code repository and deployment processes.

• Extremely well integrated with practically any relevant technology utilized to deploy and manage processes for applications.

I go by @nnennahacks on Twitter. Let’s chat!