What really drives good documentation?

A look at the differences between AWS and Azure

I’ll admit it, this one is rather abstract, but I'm often curious about how developers consume information. There is obviously a lot of video content these days, but in reality, engineers will still look at the documentation to help build their stack for reference material. Maybe there is more of a drive towards GPT, etc., but that won't replace the tech docs quite yet because things change faster than the LLMs can be trained. LLMs also don't necessarily provide you with the broader context and linking material that the tech docs can.

So, what makes the documents helpful? I went on a deep dive into Azure and AWS documents. While I've been happy with the AWS documents for years, I struggle to parse the Azure documents and wonder why.

The Entry Point

Let's compare something similar across the 2 cloud providers. Object storage accounts.

A Google search for S3 lands on the S3 front page. It's clean, with minimal information, but the eye is drawn towards the boxes in the middle; of them, there are few to choose from. My brain knows it wants S3 and not Glacier, so I have the user guide or API docs to choose from. It makes that choice simple.

When I open the same link from Azure, I'm bombarded with information about Architecture, Getting Started, Developing applications, and so on. There is a lot.

Using Object Storage in My Application

Let's pretend we want to use object storage within an application. How do we figure out what we want?

It's a user guide, I guess, so let's explore what AWS offers. The first page of the User Guide is text-dense but easy to scan. What is Amazon S3?

The first link in the left sidebar is "Getting Started." Let's look at that. The second link in that guide is "How to Create a Bucket." Cool, I need one of them! The page is a 17-step guide to creating a bucket, including more technical aspects like S3 Object Lock, Key Management, Encryption, Versioning, Tags, and more. All this stuff will be handy, but they keep it concise and link to more relevant pages.

So I've got my bucket. Let's look at step 2, uploading an object. Ah, this page isn't what I'm looking for, as it runs through manually uploading an object to storage. So, let's find out how to upload a file using the SDK. Down the sidebar, I find Developing with Amazon S3. It seems promising. Inside of there, I've got Using the AWS SDKs. It seems perfect. I get a direct link to the SDK and code examples when I open that page.

We'll leave that there for now and compare this with Azure. So, I return to the Azure page.

I need to do the same. I need an account to store things and a bucket to upload data using the SDK, so let's get started.

The How-to guides are an excellent place to start: Create a storage account or a block blob storage account. Eh? What's the difference? And why do they both link to the same place?

Never mind, let's create that account. We want to use a portal like AWS. The first bit of content I'm hit with is a Storage account type parameter. This is a lot of information for me to take on. Do I want:

• Standard general-purpose v2

• Premium block blobs

• Premium file shares

• Premium page blogs

• Legacy standard general-purpose v1

• Legacy blob storage

Argh. It's not like I have a choice; I have to decide to create an account to create a container. Luckily for me, just below are some screenshots of the portal. But with this comes far more tabular documentation….

• Basics

• Advanced

• Networking

• Data Protection

• Encryption

• Tags

• and finally, Review and Create Tab

a lot of documentation consumed later, I'm in a position to create my storage account. What is nice is that I can switch tabs to see associated docs for Powershell, Azure CLI and more. But I do wonder if its too much in one place. Anyway, let's press on, a 17-step how this is not…

I now have to head back to the landing page to find out how to create a bucket, as it's not in the storage account docs. Quickstart, though, has the titles Upload, Download, and List Blobs—Portal. Sounds promising!

This document is much shorter, but the prerequisite was a storage account, so I've not missed anything in creating one. That was legitimately the first place I had to go.

Creating a storage container is a straightforward six-step guide with a screenshot. It's nicely laid out and light on text, a nice intro for people who've already been beaten down by the storage account docs.

I now have a storage account and a container, and I would like to upload a file to my container using an Azure SDK. In the sidebar, I spotted the Go SDK link in the same quickstart section, so I hit that.

Connecting Applications

AWS

We're now at a point where both platforms have figured out how to create a bucket. But how do we upload a file to them? Using an SDK, of course! In our case, we're going to look at the instructions for the Golang version in both environments.

Where did we get to with AWS? If you recall, we clicked through to the SDK, which gave us a landing page for the SDK and a link to the SDK examples for Golang.

So what next? Let's see if we can find an example and explanation of how to upload a file. Again, we're faced with a number of boxes, all clear and clean in what they offer. We will choose the Developer Guide.

We're directed to a new site. If I'm honest, it's not as pretty as the AWS manual to date, but my guess is it's probably driven via an automated documentation build process leveraging a generic framework, so I'll let them off!

The first link on that site is a Getting Started page. It seems like a good spot to start. Again, it's a short enough page, concise in its content, and it walks you through installing the SDK and setting up an access key.

The bottom of the page explains how to invoke an operation using the SDK, and it usefully shows you how to list objects from an S3 bucket! That's half the battle right there.

Back on the landing page, I need to figure out how to upload a file using S3. Nothing obvious stands out, so let's search.

Ah...., the search is broken.

That's a shame; it had been very easy to date.

The bottom of the homepage, though, is Code Examples. Let's see what we can find. Click through, and then a very clear list of examples appears, and usefully, S3 is in the list.

If I click through there, I see a list of pretty nondescript operations, which is a little disappointing. But PutObjectV2 sounds roughly like what I want, so let's have a look.

Urgh. Clicking through just drops you at the top level of the Code Examples repo for Golang. It could have been much better had you seen the Getting Started page. Never mind, though. There is an S3 folder; let's take a look.

The readme is helpful and links to a lot of everyday operations. One of which is the PutObject example, and it tells me pretty much what I needed to see:

It shows me how to upload a file and handle basic errors. From the Getting Started Guide, I know how to connect the SDK to the Cloud service.

Overall, it's not bad. It could be easier to find common stuff in the SDK docs, but it didn't take long.

Let us see how Azure compares.

Azure

So we're on the Azure Go page where we left off. Again, like with the bucket intro, it's certainly not as concise, but it does a similar job: installing the SDK library and then connecting it to Azure. To my eye, it seems more convoluted. That's not the docs' fault, though; that's the way Azure works!

They have a sample, but rather than walk you through the code locally, you must check out a Git repo, which is a bit sad. I'd rather see how this works within the structure of my own project than another random Go file.

The rest of the sample section, though, does walk you through the code, which is good. Where it actually starts to shine is when it walks you through creating a container, uploading a blob of text to a container, and then, to cap it off, listing the blobs in the container!

It finishes off with downloading the blobs and cleaning up.

This is really good. Also, in this section is a link to more Go blob management and details of how to perform more complex blob operations.

Conclusion

Having played this little game shows that, in this example, there isn't much between them. AWS makes finding what you're after easier, and a cleaner, less cluttered interface makes digesting this information more accessible.

Conversely, Azure's blob docs gave me everything I needed in one place but not a cohesive code block; I had to piece bits together. The other problem I have with their layout is, for me, at least, docs in dark mode; I really need help with it. However, the narrow viewport and swimlanes of additional links on both sides are also distracting. There are just so many hyperlinks to other content on the site. This might be good, but I can never work out if I'm on the right page.

Everyone is different. I would rather the Azure docs be less verbose, but they do a job. I guess people who have been Azure users for a long period of time find them easier to navigate. On the other hand, I find that navigating the AWS docs is generally easier, but as we've found out, finding code samples might drive you to a different portal or straight out to (Microsoft-owned) Github to help you find what you're looking for.

What do you look for in good documentation?