Does Energy Really Flow Where Attention Goes?

The Wind

Energy Flows where Attention Goes, is attributed to Tony Robbins, though it may go back to James Redfield. But are they correct?

Often, they are. When you think positively about things, energy tends to go there. Take coincidences for one thing. Once you start noticing something, you tend to notice more of it. Like if I just buy a certain car, perhaps a new Electric Car, you tend to notice that car on the road, you tend to notice more electric cars on the road.

Yet, there are times when energy doesn’t go where you put your focus. What’s up with that?

Perhaps a couple of things. One is that maybe you’re trying too hard. As Yoda said, and grasshopper’s teacher before him, There is no try. And, probably by trying too hard, you’re not enjoying life or the journey enough. You’re probably not enjoying the breakthroughs enough, no matter how tiny they are.

Two, the current flows where it wants to flow. There’s nothing you can do, short of a dam, to change it. And making a damn requires either being a beaver and having to pay huge dentist bills, or destroying the current ecosystem and perhaps several homes.

Expressive Forms – Part 4

Programmer

Previously, I talked through setting up a calculator form. This time, it’s a menu form. And, I’ll tell you where to get xf_form.js (free) for the helper routines.

A menu consists of several buttons. Each button links to a webpage, except those few buttons whose task it is to expand or collapse the menu. Since there is no submit button, this wouldn’t need to be a form. Yet, making it a form with readonly input fields, means that you have several less divs on your webpage. And I’m always grateful to have fewer divs to have to tell apart.

So, let’s make it a form. As with all the forms I’ve presented, there’s no action or method on the form. The form has an id, and it has an onsubmit attribute. For the menu, onsubmit is not really needed. Each button has the type of “button”. But, just in case the browser says to itself, there must be some onsubmit button, I added onsubmit=”event.preventDefault()”. This keeps the form from ending up with a blank menu.

You can go ahead and set up your menu buttons. If you want emoji on your buttons, my x_press.js library has several which are appropriate for menus. To use the home emoji, just enter &menu_home;. x_press() will interpret it for you. However, since your menu will be on every page, you’ll probably write it as a javascript function. If you do that, you’ll need to change &menu_home; to %menu_home; and call x_press a little differently. Or, you can just go to Emojipedia and copy-paste the emoji from there. xf_form.js relies on x_press.js, so you’ll be adding them both to your <head>. I’ll point the way at the end of this article.

xf_form.js helps with the expand / collapse menu buttons. These use the onclick event, rather than an <a href=…>. Each button has a data-menulevel attribute. I made the first level 0, then 1, then 2. But these routines allow you to assign whatever levels you want. You could start with 10, then 9. You don’t need to go in order, but why confuse yourself.

So, on my menu, all permanent buttons have data-menulevel=”0″. One of those permanent buttons is the menu button. This used to be a triple bar, now it’s a triple dot, as that takes less room. The menu button, expands the menu by opening menu level 1. The menu button also closes menu level 1 when it’s open. So, the menu button toggles menu level 1.

My menu has 3 levels (0, 1, and 2), so the onclick for the menu button is onclick=”xf_menu_close(‘menuform’,[2]);xf_menu_toggle(‘menuform’,[1])”. Close menu level 2 for form with id=”menuform”, then toggle menu level 1. There’s also xf_menu_open. These change the style visibility between visible and hidden.

For instructions on how to use my x_press.js and xf_form.js libraries, go to my Really Useful Javascript webpage. These libraries are light-weight, so they won’t slow down your site. Just keep in mind, that I change these libraries at will. Mostly I add new functions. But sometimes I have to revamp an existing function. And if you’re using that function, it may no longer work. So, contact me from my website to be notified of any changes I make. And, if enough people sign up, I may create new functions, rather than revamping existing ones. That way, the existing ones will still work. Yet, there are times when Google forces me to rewrite functions and not leave the old ones. So, sign up to stay informed. I promise I won’t spam you.

Expressive Forms – Part 3

Programmer

Previously, I explained how to create a contact form. In this part, I’ll explain how to create a calculator form.

In order to evaluate a math equation, you first have to parse it. Then you have to evaluate portions of the equation in the correct order. There are javascript libraries which will evaluate equations for you. I looked at 5 or 6 of those. Not too hard to implement, however, you have to specify the equation the way they want you to, not in mathematical format. So, I wrote my own in xf_form.js.

To parse the equation (separate the values from the operators), you need some sort of parsing routine. Those are very complicated to write. So, instead, I make the website programmer place the separate values and operators into an array, in the order of the equation. I figure, they already know and have access to those various parts. So, parsing done! Oh, just make sure the values are numbers and not strings.

Then I wrote a simple routine to evaluate the equation from the array. You can use operators **, *, /, +, -. These are evaluated based on mathematical rules – ** first, then * and / left to right, Then + and – left to right. I was going to provide for % (remainder), but who knew what order you wanted that evaluated in.

I provide input fields for all the values and operators. The operator fields are readonly, though you could not make them readonly and let the user enter their own equation. Because the keyboard operators threw off my vertical alignment, I display other similar symbols, but the value is still the keyboard operator.

But, your equation still might have nested equations: 1+2*(3+4). 3+4 is nested. Innermost equations are evaluated first. I used data-calceq to specify the level. For 3, +, 4, data-calceq=”2″. For 1, +, 2, *, data-calceq=”1″. Now I need somewhere to store the result of 3+4. I call this hidden input field xf_calc_resultN where N is the level number – in this case 2. xf_calc_result2 has data-calceq=”1″.

Now I call my routine to evaluate the form, passing the form id. Form has data-calceqs=”2″ (the number of equations). My routine gets all the children (descendants) of the form. It evaluates the equation where data-calceq=”2″. Then it evaluates the equation where data-calceq=”1″. If you had 10 equations, it would evaluate them from 10 to 1.

The result of equation 1 needs to go somewhere. I place it in an output field with id=xf_calc_result1.

onsubmit=my form evaluation routine, evaulates the form when the user clicks the submit button, which I’ve titled Calculate. Everything’s fine, all javascript, all simple, all client-side. However, there’s one wee problem. As soon as the user clicks the submit button, the equation is evaluated and displayed, then the form is cleared. To keep the form from clearing, add another function to onsubmit. onsubmit=”xf_calc(form_id);event.preventDefault()”. The Default that is being prevented is clearing the form. That’s not technically correct, but that’s what appears to be happening. What is technically happening is not really important. What’s important is that your form isn’t being cleared and the user can see the results.

If your formula’s not too complicated, you can use xf_calc. Otherwise, you’ll need to call xf_math_eval(equation_array) multiple times and piece together the results. You can still use hidden input fields for intermediate results.

Stay tuned. Next time, I’ll finish up with a menu form. Then I’ll tell you where you can find out more about xf_form.js.

Expressive Forms – Part 2

Programmer

Part 1 was an introduction to Expressive Forms. In Part 2, I’ll cover a contact form because a) that’s probably the one you’re most interested in, and b) it covers the most ground.

With a contact form, you want to collect at least an email address and receive that email address in an email to yourself. You probably also want to collect the potential client’s name. Perhaps their phone number. And, some info about why they’re contacting you.

Most email forms reach out and grab you. I hate when that happens, so I don’t advise doing that. Rather, make the form obvious (or the click of “Contact Me”). Let the user reach out. After all, I want clients who want to engage with me, rather than those who happen to be swept to my shore and almost drowned in the process.

So, go ahead and design your form. On my test contact form, I had Reason for Contacting Me. This is typically a list of choices including “Other”. If you want a list, use a <select> element, otherwise, use an <input type=”text”> element. With <select>, you place each option in <option> tags. And you can group <option>s in <optgroup>.

Next, I want their name – <input type=”text”>. For each field where the user will enter something (or select something), I use a <label>. <label> is related to <input>. <label for=”name”>Enter a Name</label><input id=”name”>. Note that the for of label is the same as the id of input. Also note that there is no </input>.

Next, for their email address. <input type=”email”>. When the user clicks the submit button, this field will be validated as an email address. The validation isn’t very robust. a@b is considered valid. You can greatly improve this validation by adding a pattern. Patterns can get long and complicated, so I won’t go into that here. The great thing is that you only have to supply the pattern. You don’t have to supply any real code to see if the email address matches the pattern.

For my test contact form, I grouped the client’s email address field and a check-box, using fieldset. The checkbox is for whether the client wants to be cc’d on the email. If they are cc’d, they will end up getting your email address. And, at this point, I think that’s a good thing. That way, they can contact me and I don’t have to bug them about it. Still, until that email goes out, my email address can remain hidden. With fieldset, I can include a legend (title for the group/set). No need in this case. Fieldset defaults to have padding which through off the alignment of my fields. I provide a class for that in xf_form.css.

A telephone number, if you wish. <input type=”tel”>. You can just as well say <input type=”text”>, since tel provides no validation. Again, you can use pattern to add validation. However, consider the reason that there is no validation. That’s because international telephone numbers can have a very wide variety of formats. If you want to limit to northern-hemisphere numbers, you can use a pattern for that. But, even UK numbers have a variety of valid formats. If you really want to make sure, the user enters a valid phone number you can use Twilio. However, if it’s me, I’m not going to give you my phone number until we’ve had some initial email conversation. So, why make me mad? You can somewhat validate the phone number with minlength=”6″. You can add a pattern to limit non-numeric input to #,(,), -, and space.

And, what is the real reason they want to contact me. For this, I used <textbox> and allowed them to enter some more text. You might want to add maxlength=”1000″ or possibly less.

Now, there’s one last field that needs to be on your form, and that’s your email address. However, if you wanted the user to be able to see your email address, you would have just supplied them with an email link. Well, it’s not so much the user, whom you don’t want to see your email address, but all those bots lurking about. The best thing you can do for that is to use an excellent webhost for your website. I’ve used Dreamhost for years – so far, so good.

Let’s continue to hide your email address – <input type=”hidden”>. Hidden fields can’t have labels. I tried checking for one and my javascript code just quit. Turns out I first needed to check and see whether my field could have a label before I checked to see if it did. So, I hid the email address. A bot can still easily see it. So, I encrypted it. I used a replacement technique to obfuscate it. I could have really encrypted it but, it’s not a password. It’s only an email address. I made the encryption easy to apply, but hard for a bot to notice and harder for it to reverse. I added that routine to xf_form.js. The routine encrypts and decrypts and allows you some control over the encryption.

I used the data-process attribute to tell this field what routine to call to decrypt the email address. data-… is an attribute that you can specify. The attribute starts with data-, and the rest is whatever you want. So data-process. You can easily retrieve whatever’s in data-… with element.dataset…. Typically, you might have data-email-part=”to” to tell you that this field goes into the to of the email. However, javascript sees that as dataset.emailPart. Since I think that emailPart is confusing – which letter should I make uppercase? – I used data-emailpart. Then I know that javascript uses dataset.emailpart.

Every field on my contact form gets a data-emailpart to tell it if this information goes into the To, CC, Subject, or Body of the email. You have to encode the spaces, and I use decodeURIContent for that.

xf_form.js provides xf_send_email(form_element) to send the email when I click the submit button. The flow of what happens is: The user enters the information into the form. They click Send Email which is a submit button. The form has no action or method. It does have onsubmit=”xf_send_email(form_element)”. First, the onsubmit action validates the form according to minlength, required, pattern, type, etc. attributes. Then it executes xf_send_email. xf_send_email goes through each element and places the information in the appropriate part of an email, encoding as needed. Then it mimics the user clicking on an email link. The user is presented with an email to send.

The drawback to this method is that the user has to click send email twice. That’s ok, you can label the first one create email. They’ll have a chance to grab my email address (though no need as they could have checked to cc them the email. And they can clean up the email, if needed. This also means they can remove information that you wanted to be required.

The good part is, no coding and their information isn’t sent over the web. Well, it isn’t sent over the web outside of the email. If you need something more, use smtp.js to keep your email address secure. In my opinion, what I’ve done is sufficient. And I didn’t have to resort to php and/or server-side code. You don’t even need to write any javascript, other than a little test script to call my routine to encode your email address in the first place.

Just create your form. Add some data- attributes. Add onsubmit=…. And, you’re done.

Stay tuned. In the next part, I’ll explain how to use xf_form.js to add a calculator form to your website. You can combine it with the contact form if you like. And, before I finish this series, I’ll tell you where you can get xf_form.js. It’s free. You don’t even have to fill out a contact form. I’m just waiting until I have the appropriate place to put that information.

Expressive Forms – Part 1

I recently created xf_form.js – a javascript library to help website programmers and designers use simple forms to make their website more expressive. Website programmers have a love/hate relationship with forms. They hate entering information into them, but they love collecting information with them. At least the website owners love the information that is collected with them. But forms can be oh, so much more than an information gathering mechanism. Mechanism, that sounds so dull, doesn’t it.

The first thing you want to do with a form is design it. Most forms have dull and boring designs. Give it some color. Place a background in the form. Make the fields transparent and show your logo through them. Just a little css for styling, and you’ve made it more expressive.

So, why xf_form.js? Well, you need a script/scripts to process the information. In the old days, you’d design a form using HTML and CSS,. The form would send the information to the back end (server-side) where it would be processed and sent to you. That’s still the way many forms are processed. The back-end code is tedious, not pretty, and specific to the form (or form type). It’s back-end so that it’s harder to hack. But why not make it simpler. In fact, why not bring it to the front end (client-side). Unless we’re talking passwords, we can still make it hard to hack. I can show you how to keep the client’s information safe. And besides, we can do more than just collect information with a form. We can use a form to process information.

I created three sample forms using xf_form.js. Well, I created them with HTML and CSS. But their data is processed with xf_form.js. The first form is a contact form. Don’t worry, I’ll explain how to have the client send you an email using a form without exposing their information to the internet. It’s simpler than you think. The second form is a calculator. Perhaps I’ll replace my form calculator which shows you how much money you can save with an Electric Car, with xf_form.js. The third is a menu. The menu could be a div, rather than a form and still use xf_form.js. I’ll be featuring this type of menu in my upcoming bookstore website. My javascript routines expand and collapse the menu.

To be continued … Check back for How to Process a Contact Form.

Deep Listening – Say What!?

Take a minute, close your eyes, what do you hear? This is not so much about auditory hearing with your ears, as it is about awareness. So, stop what you’re doing and focus on what you’re aware of.

Minute #2: There’s the war in the Ukraine. Why doesn’t it bother me more? What is it that I’m bothered that my government’s not doing? Why does this bother me and the wars (multiple) in Africa do not? Do I think of these wars as “conflicts” because that makes them less disturbing?

Take a 3rd minute. Walk outside. Here, it only feels like 10F (-12C). So, maybe not today. But when you can, go outside. Or, at least step outside in your mind. What does it feel like? Are you in a concrete jungle? Is there any life? Whatever speck of life there is, even if it’s people, how does it survive? How does it thrive? If you’re in your yard, what wants to come forth? Yes, invasive weeds including grass. But, why are the weeds there? And what would come forth if it could? How can we nurture it?

Minute 4: What thoughts are there in your head? Can you lightly push aside those that don’t need to be listened to right this very second. What is your deep mind trying to tell you? Take another minute to listen to your breath and your pulse. Are they OK or are they trying to tell you to do something different? Minute six is for your gut. Is your stomach rumbling? Maybe you should eat. Nobody’s happy if the gut ain’t happy. Why is yours not happy?

Minute 7: Hopefully, you’ve slowed down enough in the past 6 minutes, so that you can easily let your thoughts drop into your open heart – that place of deep understanding. If not, follow your breath as it goes by your heart, until all of a sudden your thoughts are resting there. What is your heart opening to? What is it closing to? Why? Should it continue in this pattern or not? What deep understanding are you hearing?

8: Listen to stillness. Listen to peace. Listen to Paradise opening up to you.

9: And as that Paradise opens up to you, how does that cacophony sound? How is that different from your normally chaotic world?

And at last, minute 10: How can order be restored to your world (or how can it be brought about for the first time)? How do you see the world becoming a better place? Who or what can help you in this quest?

The Guide to Going Green With Solar Panels

Image via Pexels

The Guide to Going Green With Solar Panels

Solar power is here to stay. With solar capabilities growing and incentives in place, now is a smart time to integrate solar power into your home. Check out this guide to solar power installation for more information from Princess Tiger Lily on just how to go green

What Roofs Work Best?

Solar panels are compatible with almost all kinds of roofs. There are, however, ones that work better to maintain a reliable foundation for the panels. Asphalt shingles are the most frequently used in roofing because of their durability and flexibility, two qualities that make them the perfect choice for solar panels. Metal roofs can also be wonderful with solar panels, though, as standing seams eliminate some of the work involved in the installation.

Tiled roofs can be more expensive to install solar panels on, but they’re still an excellent option due to their sturdiness. Even flat tar and gravel roofs can be good hosts for solar panels, though you’ll need to ensure the panels can be angled to optimize their output.

How Do You Install Solar Panels?

To install solar panels, you’ll first need to decide the best place for them to be placed. Check out the roof for the best angles and directions to maximize sun exposure and increase efficiency. Once you have the location, build the platform for your panels to be installed on. Ready your dedicated conduits to be connected to your platform.

Affix the solar panels to the platform using professional tools. Depending on the type of panel and platform, you may need brackets, pincers, clamps, bolts, meters, and tubes. Once the panels have been placed, wire them together using junction boxes and fuses. Then you may connect the panels to the electrical components. Because installing solar panels can be dangerous, it is worthwhile to engage a professional to complete or help guide the installation to eliminate accidents and guarantee power production. 

What Should You Expect Once Panels Are Up and Running?

Your solar panel setup, the amount of sun your panels can get in a day, and how much electricity your home uses will determine how much power your panels can generate, but all homes with solar panels properly installed should see a substantial decrease in power costs. Some solar panels generate enough power that homeowners are able to get credit from their electrical company due to the overabundance. Most solar panels are good for 20 to 30 years, with their efficiency diminishing over time.

What Programs Are Available To Offset Costs?

For those with a Federal Housing Authority home loan, the Department of Energy suggests utilizing the FHA’s Energy Efficient Mortgage program. It is an excellent way to get the costs of energy-efficient improvements to a home added to an existing mortgage. There are guidelines that must be followed, but qualified applicants can get a significant amount of the costs of going solar covered by the addition to the mortgage, if not all.

The federal government also offers a solar tax credit to those who have installed residential solar photovoltaics. The eligibility rules for this credit state that the solar panels must be owned by the person claiming the credit and have been used to provide power to a qualifying structure. Some states also offer energy rebates or tax credits for those who have installed solar panels and use them to run their homes.

Bringing solar panels into your workplace is not only a great investment for long-term energy savings, many states offer financial incentives for solar energy users including rebates and purchasing back energy.

More and more people are going green. If you’ve been considering ways to bring your home into the twenty-first century, now’s the time. Take advantage of the incentives available today.

The mission of Princess Tiger Lily is to help you find green, organic and/or fair trade companies for your purchases.

Coloring Google Charts

Programmer

I recently updated my xg_graph.js javascript library to allow coloring of Google graphs. (Google calls them charts). xg_graph.js makes drawing bar, column, line, pie, table, and geo charts easier. Line charts can contain lines or points or both. Pie charts can have a hole in the middle, in which case they’re a donut chart.

So, what can you add color to on a Google graph? Google graphs have colors by default, so you’re not adding colors, you’re overriding colors. This is even true, when you’re giving the text a color other than black.

For a bar chart, you can override the colors of annotations, the background, the background of the chart area, the colors of the bars, items along each axis, items in the legend, the title text, the tooltip or hint (the text that appears when you hover over something), and trendlines. You can maybe override background color, text color, border color, and/or transparency, depending on what you’re overriding the color of. Note: To override transparency, you override opacity which is the opposite of transparency. When will css add transparency to styling? That’s what I’d like to know.

While you can override colors for all those various things on a bar chart, xg_graph.js only allows you to override the primary coloring, which is for the bars. Bar, Column, and Line charts come in two basic fashions. In the first one, there are single bars/lines. In the second, there are multiple. When there are multiple, these are called series. The first of the series is called the primary. In the case of bar and column charts the series can be stacked on top of the primary.

So, the question comes, if you’re coloring the bars are you just coloring the primary bars, are you coloring the series, or both? Let’s talk about the series first, because that’s easier to color. You can color the series with the colors option. Just provide an array of colors. There is also a series option which accomplishes the same thing. However, you have to provide an array of objects, whatever those are. I use the colors options.

Google graphs use 31 default colors for the series. If you have more than 31 series (and why would you), the colors start repeating. In 2014, Google start providing Material charts. Material charts use Google’s Material Design Colors. When coloring series for Material charts, the first three series are different shades of blue, then next three are different shades of red, then orange, then green, purple, aqua, peach, gold, blue violet, pink, and now we’re up to 30. Even though it’s been 8 years, Material charts are in beta.

To color each primary bar differently, you have to add a style column to the data array. In your data array for Google graphs, the first row is headings. The heading for the style row is {role:’style’}. The brackets indicate that this is an object. This column for the other rows can contain the color ‘red’, or an object which is the style {color:’red’,opacity:50%}.

If you’re confused at this point, don’t worry, I’ve made it easy. To draw a graph with xg_graph, you place some code in the <head> of your webpage. Then you call xg_graph_google_init(‘bar’) or whatever graph type you’re drawing. This sets xg_graph_color_scheme to ‘default’, which will make it use the default colors. Then you set up your data array. To change the primary bar colors, change xg_graph_color_scheme to ‘primary’. Define a color array, and call data_array = xg_graph_google_apply_color(data_array, color_array). If you don’t specify enough colors, the colors you specify will be repeated. This adds that style column to your data array for you. To change the series, set xg_graph_color_scheme to ‘series’ or to ‘primary+series’. Then call xg_graph_google_apply_color(data_array, color_array). The data array doesn’t need to be updated, so don’t say data_array = …. Series colors are kept in a global array behind the scenes.

Let’s talk about pie, pie graphs to be specific. Donut graphs aren’t separate from Pie graphs for Google. You just specify the size of the pie hole. If there’s a hole, it’s a donut graph. It’s too bad that you can’t make the hole transparent and place an image of ice cream below the pie graph. Then you’d have a pie a la mode graph. Well, maybe you can, try setting background color to ‘transparent’. If you get this to work, let me know.

Another thing to note: Pie graphs can be 3D. Donut Graphs cannot be 3D. Pie graphs are the only type of Google graphs which can be 3D. You can somewhat fake 3D for Bar and Column graphs, by specifying border colors in the style column. I provided for 3D Pie graphs. I didn’t provide for fake 3D Bar graphs.

For pie graphs, xg_graph_google_apply_color colors the slices. This could have been done with either the colors or slices option. I used colors, because slices is an object, so more difficult. These colors work the same way as series. But, since there is only one option, you don’t have to change xg_graph_color_scheme. It is changed for you.

Geo graphs are maps made of line drawings. Google also has map graphs which use google maps and markers. Markers and colored text on geo/map drawings require you to obtain a maps API key and let Google Graphs know what that is. I didn’t provide for that.

By default, Geo graphs color the regions/locales in your data_array with a white-green gradient. A gradient varies the color based on the gradient colors. So the countries with lower values will be more white. Those which higher values will be more green. Geo graphs are always going to color locations based on a gradient.

For Geo graphs, it looks like you’re stuck with a gradient. However, you can give that gradient whatever colors you want, and as many colors as you want. Call xg_graph_google_apply_color(data_array,color_array). For the previous graph types, colors in color_array are repeated until there are enough colors. For Geo graphs, they’re not. If your color_array contains red, orange, yellow, green, blue, and violet, the countries will be colored using a gradient made of all those colors.

But wait, what’s this? If your data_array contains n locations and your color array contains n colors, each location is colored differently. If you want to color each location with a separate color, xg_graph.js also allows you to do that with an svg (a specific image type) map. You have to provide the svg.

And last, but not least, table graphs. A table graphs displays data in a table. The user can sort the data. You’ve probably seen these somewhere on the internet. Perhaps in Wikipedia. In a table graph, you may want to sort the various rows. By default, Google uses a white lavender gradient for the header row. Then, every other data row has a background of snow. With xg_graph.js you can apply background coloring to the header row. You can also apply coloring to either all data rows or to every other data rows. Table rows are styled using the cssColorNames options. This is an object containing the class names to be used in styling the rows.

In xg_graph.js, you need to provide the following classes, if you want to color the rows: xg_table_header_color, xg_table_row_color, and xg_table_alternating_row_color. Each class should contain background-color. The header row background color will be a gradient of white and whatever color you specify. If xg_graph_table_alternating_row_style=true, every other row background is colored. Since these classes are styles, and since you’re providing the classes, you can specify more than just background-color. Since coloring a table graph is based on classes, rather than the data array and color array, call xg_graph_google_apply_color(”,”) to apply coloring.

That’s it. If you want to provide other coloring or if you want to color other types of google graphs, you’ll need to code that yourself, unless you talk me into providing that capability in xg_graph.js. I provide the simpler coloring. The rest looks like it gets more complex.

Rhiana, Mother of Trees

The Wind

There she sits among the trees
Talking to them
Feeding them
Nurturing them
Loving them as deeply as deep can go

Who is she?
Rhiana
She is their mother
She is the one who cares for them above all others

Selvene is in the ocean
Caring for fish and reef
Teaching them how to live their best life
Blowing them bubbles of joy

Selvene is their mother
She cares for them deeply

The mountains too have their mother
And the air, the butterflies, and dragons

Those walking the land, the mammals
Their mother is Qgore
She strokes their fur
As she kisses them
She sings them lullabies goodnight
And then loves them till morning
When she starts to care for them all over again

Birds ride in invisible airships
They climb the unseen stairs
Who put those there for them to find?

K’tani the elevated one
She who once was an albatross
And long ago, an archaeopteryx

K’tani, like Qgore, Selvene, Rhiana, and the others
Has been there forever
She knows what it’s like to be cared for
For once, she too was young
Once, she too had a mother who tucked her in at night
Her mother was Honua, Isi, Toprak, Zelmja, Terra
Earth was her name
Earth was the one who cared for all

We too have a mother who cares for us
She cares as deep as the core of the Earth
For that is where her heart is
She pulls us into her sanctuary
That bless-ed place within

She pulls us in to her heart of hearts
For there, we learn to care
There, we find our own heart
There, we know what others need
There, we all become mothers
To the next generations of hearts

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.