Documentation – Good, Bad, and Don’t Go There

Documentation applies to lots of things – programming, writing books, financial records, and conversations (but I won’t go there). It’s a good thing that we are more than what’s documented about us. And sometimes, it’s good that we’re nothing like what’s documented about us.

If programming, and this applies to other areas, there are various types of documentation. There are comments in the program. Yet, comments are not always updated. So, if they’re documentation, they may not be current.

A friend of mine would use function names to tell a story. Some books do this with chapter headings. While creative, those types of comments are usually not documentation.

There are high-level and low-level comments in a program. High-level tell what each function does. Low-level gets into the details of how that function does what it does.

There is also (or should be) documentation about a program outside of the program. This might include the before and after. The before might be programmer specs, but sometimes those are kept up-to-date. This external documentation should have one easily findable final version. It should be obvious that that is the final version. This external documentation should speak to everybody who needs to know – CEO, Managers, Analysts, Programmers, Internal Users, and External Users, and Vendors, and Partners, and ….

In the case of a book, documentation might include a Table of Contents, an Index, Notes for the Reader (I sometimes include a who’s who of characters), About the Author, and Description. This documentation needs to be understandable by everybody who reads it. Sometimes for the description, I just include a section of the book. I probably should include a little more.

So, documentation needs to be organized (yikes). And it needs to be understandable by all the various parties. Often techies write documentation from the computer side of their brain. I don’t, but I might be a rarity in that respect. As a writer, I need to write the Description so that the reader can understand it. (I also need to write the book so that the reader can understand it. So, I try to make my computer and other reference books easy to understand.)

There are situations where you don’t need to make documentation understandable by all. Who’s going to read the comments in your program, other than another programmer? But even then, not all programmers understand coding at the level that you do.

I worked with three sets of documentation (not my own) recently. The first was with Paypal. It took me two months to get Paypal to work on my website. I didn’t spend 8 hours every day on it. But I did work on it most days. Some of that time was getting my page to work the way I wanted it to, which had nothing to do with Paypal. And I would have gotten done a lot sooner, if I had contacted support. But I wanted to keep track of what I had done and understand what I was doing and why I was doing it.

I blame the process taking so long on Paypal’s documentation. I just wanted to add the buttons – no programming involved, the documentation said. Paypal has a nice button generator. You just paste in the code they give you, and nope it didn’t work. The documentation about the button and how to set it up, didn’t explain it well to me. Me being somebody who didn’t have a good idea how I wanted the button to look and why I wanted it to look that way? The documentation wasn’t from a business point of view or a beginner’s point of view. It was more technical. It was left-brained. It was almost written for those who already knew what they were doing.

Also, the documentation kept taking me into how to program – when there wasn’t supposed to be any programming involved. And, several of the links in the documentation got 404 errors (page not found). These were links to other places in the documentation. I guess nobody checked when they renamed or removed a link, if it was referenced elsewhere.

The documentation talked about registering the app. It finally told me that the default app is the button. I hadn’t bothered registering because I wasn’t using an app. I was using a button. The apps in my mind were those things which took programming.

In the meantime, I decided to write some helper routines for Google Graphs. Google Graphs are nice and easy to understand. However, the data is mostly hardcoded – no real chance to change it. You can get the data from an external source. I just wanted to be able to change it. Since I was doing something abnormal (out of the ordinary), that documentation was harder to find. But, I found it without too much problem. And there were no 404 errors.

Sometimes, I found myself reading about something, only to find out after much more reading that it’s no longer done that way or this feature is only in beta (not really ready for production). Google Chart’s documentation is for programmers, so it didn’t get too generic and didn’t really need to.

Still, the documentation introduced a couple of programming techniques which were new to me, without really introducing them. They were just presented it with little or no explanation. It took some time for me to wrap my head around them. I would consider these advanced techniques. Maybe they should have had a separate section which explained these in more detail. Overall, Google Charts documentation was good.

I also recently added a Buy Me a Coffee button to my website, in case people want to make a donation. (hint, hint). Their documentation was also good. What was missing were some hidden features, that perhaps I shouldn’t be using. The default icon for the button is the Buy Me a Coffee logo. Buy Me a Coffee allows you to change this icon to an emoji. There are many choices for the emoji, but not all emojis are available. You can use those non-available emojis (cut and paste from Emojipedia), but only in certain situations. The default icon/logo is an image. You can place html where the icon goes to use your own image, in some situations. I did that. You can also use html to stylize the text.

Other things that are hidden, or harder to find than they should be: You can set how much you want each cup of coffee to represent. This can be $1 to $5. The person donating, can only choose 1, 3, or 5 cups of coffee. So, the maximum that can be donated is $25, unless I missed something. You should also set up your payment page, which can be different from your button. Still, they should go together thematically.

I would have liked to have those things explained up-front – before I signed up. I still would’ve ended up signing up. But I would’ve researched other options longer. I also wouldn’t have spent my time figuring out that the break-even point between Paypal and Buy Me a Coffee is $25. If it’s less I end up getting more when someone pays me through Buy Me a Coffee. If it’s $25 or more, Paypal takes less away. Oops, Buy Me a Coffee doesn’t allow donations of more than $25. And, I take it back. Yes, I would have done that analysis.

So, how do you ensure that your documentation is good, that it speaks to everybody, that there are no holes or at least no deep pits, other than the unavoidable ones like external links which no longer work (or which no longer work the way they did when you created them)? The best answer, is to get another set of eyes to look at it. But don’t just get any set of eyes, get a set of eyes who has the perspective of someone who’s looking at this from outside, who knows what they’re talking about. If this is technical documentation, IMHO it’s good to use a non-technical tech writer (documenter) or a technical techwriter who can write non-technical documentation, like myself. Get somebody who doesn’t know your business. If it’s a book, an editor is a good choice. However, if it’s the description, you may want to get a marketer’s opinion. After the documenter’s done, have other parties review that documentation to make sure they understand it from their viewpoint.

I don’t always do that. I’m good at writing technical documentation. I’m also good at writing books. I’m good at editing. However, one of my book edits is to have the computer read the book back to me.

I also use Word’s spell checker (now Editor) as my first edit. Even so, I don’t accept all of its corrections. Neither should you accept all the corrections / suggestions of that other set of eyes.

I have Editor set to show me the reading ease and grade level. If the ease is less than 70 or the grade is higher than 6, I often go back and make the book easier to understand. Usually this requires me to break up long sentences, but at least me long sentences don’t run on forever and ever, taking up several lines and getting convoluted while they’re at it. Oh, really?

Another reason that I don’t usually have someone else do documentation for me, is that there’s the question of having the money to pay them. But Paypal, Google, Buy Me a Coffee – they can probably afford this.

One Final Note: I wonder how many small business owners tried to put Paypal on their website. Maybe they were partially successful. However, they couldn’t understand how to make the transition from the button code to the testing platform (sandbox) to production (live – where the money actually gets to you or at least to your paypal account). How many of them gave up? How many of them switched to some other payment transaction platform? How many of them think that the button is making them money when it ain’t because they didn’t make it live? Is bad documentation costing you money, or time?

I thought about giving up and switching to a different platform, but all the other popular platforms which take credit cards, required a monthly fee. This includes Selz which I had used previously. Selz didn’t notify me or if they did, I missed that they changed to requiring a monthly fee. I wasn’t paying, so they dropped my account. I only found out because I happened to check it one day. I usually get paid outside of my websites, so I wasn’t too worried about it. Selz documentation was good. It was easy to add the button.

A non-functioning button, caused me to be more cautious about adding Paypal. And that caused delays – I wanted to get it right.

I did have a different payment processing something-or-other on one of my websites before Paypal became really well known. But let’s not go there.