AWS Documentation is Awful

This past week I had a coworker ask me to help with some Amazon Web Services (AWS) administration. I needed to go in and check the last time a handful of users had logged into the system. I had been shown how to do this in the past but didn't do a good job of taking notes. I didn't worry about it as I figured I could just use an Internet search engine to help me get the information I needed. That didn't work at all.

AWS is such a large system that there are half a dozen ways to get the information I needed. Furthermore the documentation kept saying to use a tool and write code to query log files. From my training at the beginning of the year, I knew there is an easy way to point-and-click my way to success. The thought of writing code felt like building a car before going to the grocery store to buy some eggs.

Fortunately I remembered some of what I had been taught and got roughly to the right place. Using information sent to me by my coworker I was able to stumble around for bit and get the information I needed. She sent me a screenshot and it provided the missing clues I needed.

I have a notebook that I keep for work. I write down notes from meetings and helpful hints. Naturally I wrote down all the steps to repeat how to get the information I needed. Logic follows that if I have had to get the information once, there is a good chance I will need it again. Next time I don't want to waste half an afternoon trying to figure it out.

Whatever Happened to Computer Documentation?

I was cleaning out a bookcase recently and wondered whatever happened to computer documentation. When I got my first personal computer, it came with 3 one-inch-thick manuals. I know that those manuals became a sore point when Apple introduced the first Macintosh computers. However those manuals were useful. In contrast, the Macintosh operating system has become so complex, it could use at least 5 of those one-inch-thick manuals now.

In the days before the Internet, you would purchase a piece of software and it would come on a number of floppy disks. Included with those disks were printed manuals that provided all sorts of information on how to run the software. As more companies started releasing more software, a certain uniformity of the documentation emerged. If you upgraded from one version to the next, you might get a whole new set of manuals but all you really needed was the release notes which talked about new features and which bugs had been fixed.

Now there really isn't much of a reason to install software on your computer as most things are run in the Internet. That's fine, but how about including some quality documentation for those sites or tools? It seems as if most companies have come to the conclusion that if you can't figure it out on your own, they don't really care. Then someone that does care will create a video and post it to YouTube to help you figure it out. If YouTube isn't the right forum, then there are any number of online forums that will have the answer for you. Does that absolve the software producers from needing to create documentation? I don't think so.

Computers have evolved a long way from command-line interfaces and the need to have bookshelves full of printed instructions next to your desk. I just wish companies would do a better job of disseminating information about their latest products and not leave it up to users to create documentation for them.

I Hate Foo Bar

The other day I was reading through a computer coding example and was confused by the words "foo" and "bar." I'm not sure how those two words crept into our vocabulary, but they are fairly ubiquitous and I don't like them. I know they are two words that don't really mean anything and are meant to be placeholders for other information, but I wish authors would stop using them.

If I was to write an example SQL query and wanted to use foo bar, it would look like this:

SELECT foo
FROM bar
WHERE gobblygook = 'more gobblygook';

While it is an example that shows the proper syntax of a SQL query, it is not nearly as easy to understand as the following:

SELECT employee_names
FROM employee_table
WHERE salary > 100000;

I don't have to translate that "foo" could also be something concrete like an employee name or that "bar" represents a table of employees. Simply by using examples that everyone can understand greatly improves readability and makes things much easier to understand.

In this age where everyone can be a published author (like with this blog) and you find yourself creating examples. Don't use "foo" or "bar." Instead, use real words that everyone will understand, even if they are just supposed to be placeholder words. Oh, and don't use "gobblygook" either.