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.

Krennelin Berry

author

A shmaltzy Romance set in the far reaches of space. This is my 109th book.

Krennelin Berry could never reveal who she truly was. Yet, she was tempted to do so, for love.
That line alone from this story, should reveal to you what type of romance this is. If that doesn’t do it, read the first few lines of the first chapter. When he kissed her, she was a queen in her castle. Oh, was this ever nice. She could stay in this castle forever.

Or, you can read the last few lines of the story, if you want to spoil the ending. I’m not judging. You’re the one who’s reading the book. If you want to spoil the ending, that’s your business.

Yes, this is a schmaltzy romance. The shero, Krennelin Berry, can’t help that she has a crush on a Celeb named Tlotl Hsen. See, even her name lets you know the kind of story this is. It certainly informed me.
All I knew, in the beginning about this story, was its title. I also knew that the title was the main character’s name. It wasn’t too long until I knew the first few lines. And that confirmed where this story was going and how it was going to get there. Well, partially. This story also has it’s share of surprises.
Now you know just a little bit about Krennelin Berry. You should also know that she also goes by K.R. And she’s a Cadet aboard a Spaceship.
Tlotl Hsen, her crush, is a Celeb. He has his own secrets, which you’ll find out about soon enough.

Some terms in this story will be familiar to you, as it takes place in Earth’s future. Others, you’ll need to learn from the story itself, for the same reason. It takes place far enough into Earth’s future that some things have greatly changed.

If you don’t like shmaltzy romances, don’t worry. I have written several romances, each of them very different. You can find them all at Stubbart.com.

Also, just because this story is shmaltzy, doesn’t mean that the protagonist is weak. Krennelin Berry has several methods at her disposal to level the playing field, especially when it comes to relationships. And, she’s not hesitant to use them. Still, timing is everything.

https://www.amazon.com/dp/B09RB5GDLX

Hardwired: Staying Wired in a Wireless Age

I just published my 108th book. I like to work hardwired. It’s faster, more secure, and there’s fewer EMFs. Plus I just love seeing all those cords dangling all over the place. OK, call me “Stuck in a rut”. Call me “Resistant to change”. You might even call me “Weird”.

The reason I wrote this book, is perhaps a selfish one. If I tell the world how to stay hardwired, some of you will. And if enough of us are hardwired, that technology will never go away. And that will ensure that I can stay hardwired.

Who would want to have their computer hardwired? Gamer’s, for one.

You can even hardwire your cellphone, should you wish to do so.

Is it worth the hassle? What hassle? All depends on your frame of mind.

Idea Tree – Book 107

author

In this postapocalyptic, earthwise, get-rich, elemental, romance, I’ve combined several genres. I’m categorizing this book as a Romance, even though the romantic parties don’t meet each other until 3/5 of the way through the book.

I wrote Idea Tree in bits and pieces with several breaks in between writing. Wow! was it ever hard to make sure that the story was woven together correctly.

It’s the year 2052, the great cataclysm has happened and now people are trying to restore the Earth. OK, so I’m a little optimistic as to how soon we’ll start putting things back together. But then again, perhaps I’m a little pessimistic about how soon that cataclysm has happened. On the third hand, some say that cataclysm is already happening.

On to happier notes: Three friends form Idea Tree to get rich while saving the Earth. Idea Tree will generate ideas that companies and philanthropists will pay them for. These ideas will save the Earth. But, these three friends can’t do it all, so they hire three Idea Generators.

A poor hispanic woman works many long hours and figures out how to start investing what little she can. Eventually she becomes a multi-billionaire (there’s that optimism again). And starts using her money and influence to save the Earth.

She’s hesitant to ask Idea Tree for help for some reason. Yet eventually, she has nowhere else to turn to save the Earth. Ian Mossiman is the Idea Generator who is assigned to help Ultresa Milan create the next idea which will really turn the corner in restoring the Earth to vitality.

And sparks fly – both metaphorically and litterally.

https://www.amazon.com/dp/B09NRH6VXT

Tongue Twisters or Knot

author

I recently decided to write a month’s worth of tongue-twisters. Why would I do something so maniacal?  That shouldn’t be too hard to do, I thought? But these tongue-twisters required more of me than writing 31 one-liner diction exercises. These had to be fun. Some had to be syncopated poems. Those which were one-liners insisted on being lists of one-liners. And once I got 31, they just wounded stop coming. Finally I had to shut off the faucet.

Enjoy such tongue-twisters as: Thin’s Shims; Path Cat’s on the Cat Path; Heathcliff’s Eclipse; Frog’s Frock; Swanson the Swan (below); Gargoyle Girl; Charles Chews Chocolate; Dr Jekyll Heckled Hyde’s Spectacular Side; Paradoxical Paradise; and Sasha Sashays.

Tongue Twisters or Knot

Swanson the swan swung
O’er the bolly belly billabong
Out o’er the water he flew
Making a heck of a swell hullabaloo

The lackadaisical lake lacked water
The faster he flew did he falter
And he barely missed three trees
By tucking in his knobby knees

Swanson the swan swung
O’er the bolly belly billabong
He missed a pilaster avoiding master disaster
Landing with haste in the past Pastor’s pasture

Why is my Enemy my Enemy

Here’s an age old question: Why is my enemy my enemy? That’s usually followed by: What did I do to them? (Or to offend them)?

I was prompted recently to look at a book that was in my Not to be Published stack. I wrote it in 2004, but didn’t like the ending. I was amazed as a reread what I had written. This book was very apropos for today. It asked these questions:

  • Why does evil always resurface?
  • Why is my enemy my enemy?
  • Who and what will save the day?

Aumanil’s: Three Paths – One History had lots of holes in the story – had to fix that. The reason I had put this book on the Do Not Publish heap was because I didn’t like the ending. As part of the rewrite, I ended up with more information at the end, twice.  So I guess there were holes there also. Now, I really like the ending, wasn’t what I had planned.

Aumanil’s doesn’t so much answer those questions, as it gives us insights into how those in another Cosmos wrestled with them. Their solutions probably aren’t our solutions. But there was one thing they did, which we will probably have to do. Somebody had to walk to where the sun was shining more brightly. For there lay their solution.

This is my 105th book.

Exploring Lost Territory

When I was young, I liked to explore the woods. Got lost a few times, Yet, that didn’t stop my love of the woods. However, I still love the ocean better.

In my 104th book, Criseilish and Bileander live on the tropical island of Vascandola. At five, they become pretend boyfriend/girlfriend so that they can play together all the time. They spend most of their time on the beach or playing together in the village. But one day, when they’re 9, they explore a place in the woods, that Bileander calls Lost Territory.

The woods are dangerous and not many people go into the woods. But Bileander is adventurous. And Criseilish is willing to go along for the fun.

But then she can’t remember what happened that day. She’s sure Bileander is responsible for her forgetting, so she dumps him.

Theirs is the relationship everyone else envies. Can she ever trust him again?

Another Romance, not TMI.

Exploring Lost Territory

 

SEA Spot Saver

Another secret about Seatac – one of the world’s most environmentally favorable airports – is the SEA Spot Saver. Don’t have TSA Precheck or Clear? You can sign up to get through security faster with the SEA Spot Saver. Best part, it’s currently free!

Yes, so, it’s only for morning flights as the spot saver is not available after 1pm. And there’s an interview required. But if you don’t have TSA Precheck or Clear and you’re traveling from SEA, check it out. Why not?

Speaking of secrets about Seatac, check out my book – Seatac Seacrets.

Book Magnet’s Author’s Lounge

I was invited by Book Magnet to write an article about my top selling book – The Wizard without a Wand. It was a good experience and well worth the effort. It would have been well worth the effort, even if they hadn’t published the article (they did). The questions were thought provoking and ones which would be good to answer about any book.

You can read the article here

And you can also sign up to try to get them to publish an article about your book in their Author’s Lounge.

Microsoft Word – Get Your Voice Back

If you suddenly can’t find David or Mark or Zira computer voice to read your word documents to you, here’s the solution!

When I edit my books, I go through 4 edits:

  1. Let Microsoft Word’s Editor help me correct spelling and perhaps grammar. Editor is funkier to use than the previous spell check. But my settings to display reading level and ease are still in force, so that’s good.
  2. Reparagraph. When I write, I don’t always split paragraphs correctly. And often, I want to make my paragraphs shorter so that they’re easier to read. I also find lots of little errors when I do this.
  3. Let Word read the book aloud. More on that below.
  4. Check for words that I commonly misspell. I created a word macro to highlight those words. By this point, I often don’t need to do this edit. However, I usually still do as I often end up reading the story once more and perhaps correct other issues or add a few more gems.

I hadn’t published a book in a few months. When I was editing the latest book, Microsoft’s Read Aloud tool had changed. It no longer used David’s voice. It was now using a female voice which I found to be grating on my ears. I switched to the male voice, and ended up switching back to the female voice. David’s voice is not the greatest. But it was better, IMHO, than either of these. But it was no longer an option.

So, I googled. And people, including microsoft, kept telling me to go to settings and choose David for Narrator voice. Well, that was still set. And Mark and Zira voices were also still there. However, now Read Aloud can’t use those voices. 

I finally found the answer. Not the greatest, but it works.

Choose a menu (ribbon in Microsoft Word), where you want to add Speak. Read Aloud is on the Review menu ribbon, so you might want to add Speak there. I have custom menus for writing books, so I added speak there.

Now, I just click on speak for David to read the text to me and click on it again to make it stop. Actually, it’s not that simple. David will read the selected text or the current word. You can make it function like Read Aloud (Read from here forward until you stop it). Press Ctrl+Shift+End to select from here forward. However, David will keep reading even though the text doesn’t move on the screen. Not helpful!

So, I select one paragraph at a time, by triple-clicking in the paragraph. Then I have David read me just that paragraph. Not the best method. But it works, and usually, I want to make some changes, unless it’s a very short paragraph.

To change narrators (perhaps you don’t like David or perhaps your local language is not US English), click the Windows Start menu, then settings gear, then search for voice or narrator. Once you get to the Narrator settings, choose whichever voice you want. If there aren’t any there, google to figure out how to install them. 

Please note that sometimes the computer reader will autocorrect for you. The error will still be in the text, but you won’t hear it. And sometimes, they really mangle words, especially the ones I’ve made up. However, that can help when perhaps I should change the spelling to something which a human reader might guess at. If that’s important.

Alternate options:

  • Use the Windows Narrator – I found this to be clunkier. Maybe you’ll like it.
  • Read your story outloud to somebody else
  • Have somebody else read the story outloud to you – I tend to not find quite as many errors with this or the previous method as I do by having the computer read to me while I edit.
  • Hire an editor
  • Use an online read such as Natural Readers – I haven’t tried it, it’s just the first one that Google returned.