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.

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.

Fixing/Modifying Table of Contents

author

I write my books using Microsoft Word. I publish them by uploading them to Amazon (through kdp.com). But sometimes the Table of Contents isn’t quite what I want. So, i have to modify it. Sometimes it looks fine in Word, but Amazon changes it when I upload it. Or they complain that it’s not right. So I fix it.

The easiest way to fix that latter problem is to save my word document as a pdf. Then I upload the pdf to Amazon. The typical complaint from Amazon is that the page numbers are past the margin. They look fine in word, but not in Amazon.

The most common thing that I want to change in my table of contents is the heading. I want it to say something other than Table of Contents or Contents. That’s ok, let word generate the Table of Contents (under the References menu). Then just change the heading. Reformat the heading if it’s not to your liking.

Some people don’t like to have the Table of Contents heading show up in the Table of Contents. I don’t mind. If you want things that way, you’ll have to create a separate section for your Table of Contents (and anything else you don’t want included). There’s also squabbling over whether to start number your book pages after the Table of Contents or not. Those are topics I’m not going to cover in this blog post.

I sometimes want my chapter titles styled differently in my Table of Contents (TOC) than the default styles. To modify those, I go to the Reference menu, choose the Table of Contents drop down, then Custom Table of Contents. Then I click Modify. I select the TOC 1 entry and click Modify again. Then I increase the font size if this is a large print book. If I just want a different font, like perhaps my heading font, I change the font. Click OK. When I’m asked if I want to replace the current Table of Contents, I say yes. Actually, I say, Why do you think I went to all this work? But that’s the equivalent of yes.

One recent book, I had originally written as 8.5 x 11. Amazon books are typically 6 x 9. The table of contents didn’t resize correctly. It looked fine in word, but Amazon complained. So I saved it as a pdf and everything was hunkydorey.

I added an About the Author chapter, which I wanted to show up in the table of contents. I uploaded the new word document and Amazon complained. I thought, this time I’m going to figure out how to fix it in word! And I did.

Two things were off. #1 the … weren’t showing up. #2 the page numbers were too far to the right in Amazon or were dropped completely.

#1. I don’t know about you, but with my astigmatism, it’s hard to tell which page numbers go with which heading without those …. In a word TOC, those … are called tab leaders. To fix those, do a custom TOC. Modify TOC 1. Click Format, choose Tabs. Change the Tab Leader to …..

#2. Fixing where the page numbers appear is a similar fix. Again, format the tabs. This time, clear all tabs. Then enter a new position for your new tab. For 6 inch wide books with a one inch margin on both sides, that would be a 4 inches. If your page numbering goes past 99, use 3.75 inches instead. You should be able to use 4, but 3.75 often works better with Amazon. Choose Right. This is a right tab because the page numbers are aligned to the right. Chose … for the tab leader. Click Set (not necessary, but feels like word might actually do what I want if I click Set). Click OK.

That’s it, problem fixed. Amazon’s happy. I’m happy. Hope you’re happy. And if you want to buy one of my books, they’re at Stubbart.com

Inviting the Writing Muse

author

So, you want to be a writer. Or perhaps you want to write better. Maybe you’re in the middle of writing something and you’re just plain stuck. Time to invite the Writing Muse into your life.

There are all sorts of mechanical things you can do to improve your writing skills – learning to spell better, taking grammar andΒ  writing classes, joining a writer’s group. You can write something in Word and then do a spell check. If you have set your options to provide the reading level Word will tell you the Reading Level and Reading Score. You should shoot for 6th Grade or lower and for a Score of 70 or higher. If you’re not hitting that score, try breaking apart long paragraphs and sentences.

Those are all good to do. You can also read more. However most best selling books follow one formula or another. Those formulas is designed to sell more books. I find that books written using those formulas to be boring. The pattern is too obvious and usually it involves too much sex and violence.

What I do is work with the Writing Muse, even for my reference books. Both the Writing Muse and I like to write. We both enjoy it. I can’t say that it brings me lots and lots of joy. However, I enjoy it enough that I’m working on book #99. Writing is a vehicle for this things that I really, really enjoy.
The Writing Muse and I have a intimate relationship. That means we really enjoy spending time with each other. For some, that relationship can be to the exclusion of all else. I have written like that. But I prefer keeping my boundaries. There are other things in life besides writing, even when I’m writing.
Having an intimate relationship means, not keeping myself distant from the story. It means, allowing the story to be a part of my life. It means interacting with the characters in my story, rather than just observing them. It means seeing what they’re seeing, feeling what they’re feeling, experiencing what they’re experiencing. Those who read my stories often express how deeply the stories touch them, how they feel like they’re a part of the story, how I’ve drawn them into the story.

All of my books are available at Stubbart.com. Get ready to not be bored. Get ready to let the stories touch you. Get ready to enter the stories. Get to know that cast and become part of the cast. Get ready to enjoy. And possibly you’ll meet the Writing Muse while you’re reading these stories. After all, the Writing Muse is the co-author.

Organize Your Writing

author

Whether you’re planning to write one book or 100, staying organized is key. How you stay organized is up to you. For me, that includes excel spreadsheets, folders on my laptop, and a very cluttered desk. Yes, one person’s clutter is another person’s organization.

I mostly organize to keep my almost 100 books straight. I also sometimes have to organize a book before and/or while I’m writing it. Tables of Contents help as does my search box. The Search Box for my books on my website at https://stubbart.com/, finds books by a word in the title, a main character’s name, a frequently used word in the book, genre, and possibly theme (like magic).

I also keep track of where I am in the process in my spreadsheets – What chapter I’m writing or Editing and which Editing task I’m performing. I also track whether I’ve published it as paperback, ebook, or audiobook (or all 3), the year, the rating, and the number of pages and words.

I probably keep track of more info than I need to, but hey! It’s my organization and I’ll do it the way I want. As should you.

What if my Book is a Piece of Crap?

author

I see this question fairly often in the twitterverse: I had a great idea for a book. I started writing and got pretty far. But now I can’t continue and I feel like what I’ve written is a piece of crap. Now what do I do?

I can quite honestly say that I’ve never written a piece of crap in my life. And if you believe that I’ve got a bridge for sale that you’d be interested in. What I ask myself these days is: Is this too formulaic? If it doesn’t flow, it’s probably formulaic. However, if I can throw in a few twists, I can usually work my way out of that mess.

There’s a few things that you should be asking yourself. 1) Is it a piece of crap or do I feel like crap? 2) Who said it’s a piece of crap – your hypercritical self or your supportive, I-can-do-better self? 3) Why do I feel like it’s not up to par? What’s wrong with it?

Let’s address #2 first. In college, I took several Spanish Courses. Both of my Spanish Teachers really liked my stories. When I took my English Lit course, that teacher didn’t like my writing. If he had, I could have tested out. I attended his class for a few weeks. He pointed out what I was doing wrong. After those few weeks, I had improved enough that I just needed to turn in my papers.

But did I improve or did I just adapt his techniques? After all, my writing was good enough for my Spanish teachers. I know that my writing improved after I took a course in logic. But when my writing really improved was when I wrote The Dancer. The story just flowed into me and out onto the page. After that, I started listening to the story. Where did it want to go?

I place my work in four stacks: A) Already or almost Done; B) In Progress; C) Ideas; D) Questionable. When my In Progress writing becomes too formulaic or I realize it’s not really something I want to write about, at least not presently, it goes into the Questionable stack. So, the first thing I do is put it aside and work on something else. Perhaps I’ll come back to it later. If you only have one book that you’re working on and it was going to make you an author, we’ll get to that.

A friend of mine writes some books on controversial topics. Those, he publishes under a pseudonym. Others, he’s had to change the title, because people thought they were purchasing something else. Sometimes all it takes is a little tweak. Sometimes you need to approach things from a different angle.

Sometimes you need to take a break. Go do something else, even if you write a different book. Do something else artistic. Go put your feet in the ocean, but not in the Pacific NW, it’s too cold. Treat yourself to something. Practice smiling in the mirror. Look at pictures of Rainbows. Breathe in good, happy thoughts.

When you’re ready you’ll pick up your book again. I may finish it. You may discard it. You may completely rewrite it. Whatever you do, you’ll create a masterpiece.

Emojis for Books

author

Hey #writingcommunity, do you use emojis in your books? Do you use emojis to promote your πŸ“š? Which emojis do you use βˆπŸ€” Why isn’t there an emoji for emoji?

I use various emojis on my website to denote book themes – superheroes, romance, wee people, shapeshifters, magic, families, time travel, etc. Check out both my children’s and fantasy pages to see most of these. If there’s an animal, cat, etc, in my book, I try to denote that with an emoji also. Note: I usually limit animals to dinosaurs and dragons, though the main character #protaganist in Cascadia Prime might be a relative of big foot. However, there’s no emoji for sasquatch.

When I’m looking for emojis, I look in three places: Emojipedia, Really Useful Unicode, and/or an Emoji Keyboard. Really Useful Unicode is my web library for Unicode symbols which are the predecessors of emojis. I use this library for two reasons: 1) Letters, numbers, punctuation, algebra, simple shapes – square, 𝕖𝓉ⓒ. 2) When I can’t think of how to convey an idea. For example, this library contains many symbols for #writing. ✍, πŸ’„πŸ€,ΰΆ«, etc.

I sometimes use emojis in my books. However, sometimes, when I upload the book to Amazon, the emoji turns into tofu βŽ• or just doesn’t show up. This is especially true of more recent emojis. It is also often true when the emoji is made up of multiple symbols, such as my superhero emoji (because there is no superhero emoji). Emojipedia will tell you if there are multiple codes used to make up an emoji when you scroll near the bottom. So, I try to remember to double check that. Another note on this: emoji flags won’t work in Windows, at least not without my Expressive Websites javascript library.

When emojis aren’t working in my books, I have to use the picture behind the emoji. The pictures for most emoji’s are copyrighted, so I tend to use the Windows, Google, or Twitter versions. The Windows version is copyrighted, but since the emoji font is covered by my Windows copyright, the picture should be also, shouldn’t it? Anyway, I often prefer the Google or Twitter version. If I need something slightly different, I can maybe find a picture on Pixabay or WPClipArt. And I often like to take something as a starting point and modify it to make my own unique version of an emoji.