Creating an External Power Monitoring app for Android

I needed to make a power monitoring system to let people know when the AC power to a critical pump had failed.

I realized an old cell phone would be ideal for this task, so long as it ran Android 4.4 (Kit Kat) or later.  I found several phones between US$20 and US$30 that would do, and these were either fully-functional used phones, or in one case, a new phone!  That's less expensive than a Raspberry Pi, and far more capable, as the phone already includes the cellular modem, the battery system, the display and the touchscreen, not to mention a whole bunch of other sensors and capabilities.

A cheap cell phone is an awesome platform!

The phone would always be plugged into its charger, and the charger would be plugged in to the AC power system to be monitored.  When the phone charger loses power, a text would be sent, and another would be sent when power was restored. The only UI needed was for the user to enter the phone number(s) to which the texts would be sent.

Being a Python rapid-development fanboi, I installed SL4A (via the QPython package in Google Play) and soon had a short console script running that did the basics of what was needed.

Simple, right?

Unfortunately, providing this simple script with a GUI and turning it into an installable Android application package (apk) was frustratingly difficult, so I decided to look elsewhere. But at least I now knew it was truly a trivial app, and I expected no significant barriers on the development side.

I installed Android Studio, the standard Android integrated development environment (IDE), and was overwhelmed by the infrastructure needed to create even the simplest app.  I'm primarily an embedded/real-time algorithm developer, so I'm used to programming very close to the hardware.  There was nothing "simple" here!  The Android platform is extremely capable, and is also quite complex.

One very pleasant surprise using Android Studio was my introduction to Kotlin, a language that pretty much eliminates the boilerplate verbosity and bloat of Java without losing any significant features, while delivering an elegant high-productivity language. I want more of this!

For fun, I also installed Visual Studio for Android, mainly to see if Xamarin's Mono would let me use Microsoft's excellent C# language to quickly develop my app.  Again, I was unable to get even the simplest demo to load, much less build.  And the full installation was nearly 60GB!

I had thought the best way forward would be to get a minimal demo app loaded and built, then modify it to meet my needs.  I was beginning to think I had a real problem trying to do even a "simple" thing with these heavy-weight programming environments.

The other recommended Android development alternative was Eclipse for Android.  But I've had an ambivalent off-and-on relationship with Eclipse for over a decade.  When it works, it's sensational.  But when it doesn't work it can be frustrating to remedy.  So, no, I didn't bother to install it.

I really wanted a straightforward tool that would take code as simple as the Python above, then with a single click would generate a fully functional apk. I had no need to see behind the curtain, so I wanted a wizard to handle all that stuff for me.

A quick search brought me to App Inventor, the ex-Google now MIT project that used the Scratch programming environment that also has a simple drag'n'drop GUI editor.  I had been wanting to play with Scratch anyway, since I plan to help with the local Scratch Day in May.  This seemed like an excellent opportunity to meet multiple goals with a single project!

While everything initially went as planned, I soon found there were features of my app that App Inventor would not support.  I then learned that App Inventor has not been receiving very much love, and there was little hope the shortcomings would be addressed any time soon.

I was delighted to find that the App Inventor code base (it's Open Source) had been cloned and improved by several groups, all of which could import App Inventor's "aia" project file format.  A quick search brought me to Thunkable, where my app both built and ran as expected.

Here's the mockup of the app from the Thunkable GUI editor:

And here's the code that drives the above GUI, with some features added since the Python prototype.  Yes, the code is an image: The Scratch language is itself graphical.

App Inventor and it's clones all share multiple ways to test your app:  Via USB Debugging, via a WiFi interface app, and via a generated apk that can be installed by scanning a QR Code.

What could be easier!

The last piece of the puzzle was to get the Power Monitoring app to always launch when Android started.  The Startup Manager app in Google Play was the right tool for the job, as well as also being able to prevent a slew of default phone apps from starting.

Playing with the Equation for a Circle.

Most of us will immediately recognize the Cartesian form of the equation for a circle (typeset using The Online Equation Editor):

Please notice that the above is an "equation" in Cartesion coordinates, not a "function".  There are various functional forms for the circle, such as in polar coordinates, but for the purposes of this post we'll stick with the above equation.

There are four "easy" points for this equation, which occur when each term of the equation is set to zero, in which case the other term is forced to take on values of +1 and -1 (the two real values whose squares equal positive one).  These four points are called the "zeros" and occur at the following coordinates:

Here's a plot of the above equation (courtesy of WolframAlpha):

As expected, we have a circle with radius 1.  Take a moment to verify that each of the zeros is indeed present.

Next, let's look at the "generalized" form of this equation, where the common exponent can take on other values:

This represents the family of equations where the exponent of x and y is the same.  However, this form has some specific limitations we need to address before we start to play with values for n other than 2.

First, we need to constrain the equation to generate non-negative values so the sum is both real and bounded.  For example, if n were odd, such as 3, then negative values of x and y would take on negative values when cubed, which in turn would force the other term to take on larger positive values to obtain the sum of positive 1, yielding a poorly-constrained result.

We will constrain the equation in three ways:

• Apply the exponent to the absolute value of x and y, instead of the value itself.  This will ensure the resulting exponentiation will always yield a positive value.
   
• Explicitly limit the values of x and y to be in the range of positive and negative 1.
   
• Limit n to be strictly greater than zero.  Please explore for yourself why this is important, though it may be best to wait to do so until after reaching the end of this post. 

Here's the full form of our generalized, but constrained, equation:

To be sure we haven't created a monster, let's look at the plot of this equation for the case n = 2:

Good!  It's still a circle with radius 1.

Notice that the point (0,0) is still at the center, but for this plot I have chosen not to draw the conventional Cartesian axes through (0,0), but I instead used axis labels and legends at the sides of the plot.  This was done not only to keep the plot itself as uncluttered as possible (which will become important later), but also to better depict the explicit bounds on x and y.  Everything we do going forward will literally be "inside the box".

Ready to play?

Let's start with a look at the plot after setting n = 1:

Whoa, a diamond?  It makes sense when you think about it: This is a linear equation, so these are the four line segments connecting the zero points.

But how did the circle of n = 2 become the diamond of n = 1?  Let's look at the plot for a value of n between 2 and 1, say n = 1.5:

What's this?  A "puffy diamond" or a "squeezed circle"?  Notice that we obtained a plot for a value of n between 1 and 2 that has a mix of the characteristics for the plots of n = 1 and n = 2.  This is not at all guaranteed, and the plots of many generalized equations fail to have this property as clearly evident as it is for this specific simple equation.

OK.  So plots for values of n between 1 and 2 also "fall between" the plots for n = 1 and n = 2.  What should we expect the plots for values of n < 1 to look like?  Let's try n = 0.5:

Cool!  A star!  Notice that our four zeros are still there.  Also notice that as n has decreased from 2, the "corners" along the diagonals have steadily moved in.  Another way to look at this is to view the portions of the plot near the zeros as getting "pointier" as n decreased.

Take a closer look at the legend accompanying the above plot: The exponent of 1/2 has been replaced with a square root radical.  This should be a hint for describing the curve in each quadrant.  Can you say what curve it is?

Let's look at the plot for a lower value, for n = 0.25:

Yup, an even pointier star.  Perhaps one with a twinkle?  It follows our intuition that the plot should get "pointier" at the zeros as the value of n decreases.

What about the plots for n > 2?  What does our intuition tell us?  A n increases, we should expect the plot at the zeros to get rounder, and the plot diagonals to move further outward.  Let's take a look for n = 3:

What's this?  A "square-ish circle" or "circle-ish square"?  Actually, the set of plots for all n > 2 has it's own name: They're called "squircles".

Let's double n, and see what happens for n = 6.  What do you think it will look like?

Yup, it's getting more square.  Notice that the sides aren't completely flat: They are still ever-so-slightly rounded.  But it doesn't look quite like the "rounded squares" we may be used to, where the corners are simply rounded to a circular arc.

Are squircles of any use?  In iOS 7, Apple switched their icon outline from a rounded rectangle to a squircle with n = 5:

Not much of a difference from n = 6, but how about compared to a rounded rectangle?

Ah, see the difference?  Which icon shape do you find to be most pleasing?  Personally, I find the squircle more elegant, making the rounded square look to have corners at each end of each corner's arc.

Why did Apple make the change?  Well, Apple may have wanted to make the change earlier, but it wasn't until iOS7 that most iPhones had screens with high enough resolution to make the difference visible enough to appreciate.

Finally, here's a plot combining the plots for n = {0.25, 0.5, 1, 1.5, 2, 3, 5}, making it more clear how the curves change with n and how the zeros are preserved:

Check Wikipedia and Google to find other uses of squircles.  Have fun!

Puck Fatreon!

I'm boiling mad at Patreon.  They just shifted their fee structure in a way that increased the cost of my pledges by a whopping 30%, while simultaneously charging Creators a flat 5% fee. That's 35% of my contribution that does NOT make it to the Creators I sponsor!

I prefer to give many small pledges to a large set of Patreon Creators, rather than larger amounts to a few. I feel this best represents my interests, and also ensures I support the less popular of the Creators I admire.

Until today, I have heard nothing negative from the Creators I sponsor about the cut Patreon takes to process and deliver pledges.

I'm listening, and am acting.

I have now decided Patreon has become a vampire, a leach on the system, and is no longer a suitable platform for supporting Creators.

I have halted all my Patreon pledges.

I hope to soon hear what new funding mechanisms my favored Creators prefer, and I will follow them there.

Go to Hell, Patreon.

---

OK, I feel better now.  The underlying problem would appear to be that the US (and the world?) lacks a cost-effective micro-payments system. Which in turn sets the stage for vampires like Patreon to appear and flourish.

Everything is strangled by the 4 major credit card networks, whose fees are growing despite a reduced cost (as a percentage of money transferred) of doing business in general, and a lower cost of transactions in particular.

The excesses in the credit card system are made perfectly evident by the presence of so many "Cash Rewards" cards, which are simply refunding some of the excess to their customers.  If you don't have one, get one soon!

A better route may be to use the ACH (Automatic Clearing House), the network used to process EFTs (Electronic Fund Transfers) such as checks, which has a vastly lower transaction fees (though this comes with lower guarantees by the network itself, which are instead taken up by the financial institutions themselves).

The best route may be to build a new micro-payments network from scratch, or expand an improve an existing one.

The Patreon debacle should hopefully cause some engagement on this important financial infrastructure issue.

How and Why Did I Become an Engineer?

During a recent interview I was asked why I had become an engineer.  In that context I gave a few key reasons.  Here's the full story.

In high school back in the early 1970's I loved all things Science and Math, but of them all I liked Biology best, by far.  When I got to take a computer programming class (using FORTRAN IV), the first program I wrote on my own was to help me calculate the metabolic rates of the rats were were raising in the Biology lab.  At that point, I saw programming as a useful tool to know, but not as anything I'd want to pursue as a career.

After high school I chose to join the US Navy rather than go directly to college.  There were many reasons encouraging me toward this path, and it turned out to be fantastically right for me.  While in the Navy I was trained in several areas, including Nuclear Propulsion. I got to operate a nuclear reactor at the tender age of 19!  I also learned lots about gyrocompasses, jet engine control systems, other types of electronics, mechanical and hydraulic system, and a ton of engineering in general.

As I was nearing 6 years in the Navy, I realized I was more than ready to start college.  During my last year in the Navy I bought an Apple ][+ with the Language Card and UCSD Pascal. My experience with Pascal was so different from my days with FORTRAN that I immediately knew I wanted to write software for a living.  I chose to attend UCSD because I wanted to be associated with a school that not only developed useful technology, but also got it into people's hands.

While applying to UCSD I learned about their Computer Engineering degree, which combined all of a Computer Science degree with the digital half of an Electrical Engineering degree.  It let me combine my desire to write software with my military engineering experience.

Upon arriving at UCSD I was immediately overwhelmed.  Six years away from high school had taken a toll, and I was far from ready for the rigor of an academic environment.  As a Freshman I was struggling to get through the brick wall of the Math sequence, though I had lots of fun with the Physics sequence, particularly the associated lab class.

In my Sophomore year I got to start on some of my technical electives, so I decided to revisit my first science love, Biology.  I was extraordinarily fortunate to be taught by Dr. Paul Saltman, a world-renowned molecular biologist who loved to teach undergraduates.  I took to the class like a fish to water, my mind absorbing the concepts like a dry sponge, and I aced nearly every test.

Dr. Saltman was unusual in that he created his post-test answer key using not his own answers, but the best of the student answers.  I didn't know this at the time of the first mid-term exam, and was surprised to hear my name and several others were called to meet with the professor one day after class.  He told us of his answer key approach, and asked if he could use our answers.  Of course we all agreed!  He then went around the group asking what year we were and what our majors were.  It went something like: "Biology", "Bio-Chemistry", "Molecular Biology", "Biological Physics", and when he got to me, I said "Computer Engineering", the only non-bio major in the group.

The same thing happened again for the answer key on the second mid-term, and Dr. Saltman started trying to convince me to switch majors.  This was two class sequence, and in the second class he really turned up the pressure, even inviting me to work in his lab if I changed my major!

I kept saying no, but I didn't really have a set of reasons he would understand, much less accept.  Then I finally came up with an analogy that worked!

I told him that every time I tested a program I was developing, it could crash and burn in any of a long list of ways, not only ending the program, but sometimes also causing the host system to lockup and reboot.  Were I to do similar experimentation in a biology lab, I told him I'd need a Biosafety Level Five containment system. Unfortunately, the Biosafety levels top out at 4.  He agreed his profession, and likely the planet, would be safer were I to stay with software, where at least we can pull the plug on the computer.

My engineering experience pointed me toward writing software that interfaced directly with the real world via sensors and actuators, rather than interacting with "users".  These are called "embedded" systems, and often require the software to work as fast as things happen in the real-world, called "real-time".  So I called myself an embedded/real-time systems developer.

My education, experience and career desires came together in my first job after college: I was hired by General Atomics to write software for radiation monitoring systems for commercial nuclear power plants.  I next worked on nuclear reactor monitoring and control systems for a new Navy nuclear submarine. At my next job I worked on automated X-Ray inspections systems for munitions, and on a neutron beam system used to inspect aircraft wings for corrosion.

I've also worked on ultra-high-speed digital video cameras (100,000 fps), on instruments for aircraft, on satellite electronics (for a mission that unfortunately never launched), communication systems for small UAVs, and on many other fascinating systems.

I had many opportunities to step into management roles, but I always chose, perhaps selfishly, to remain a software developer specializing in instrumentation and embedded/real-time systems.

My focus on instrumentation meant I did only a minimum of user interface and web development, and no mobile development at all (other than writing the occasional device driver). I wrote no business or enterprise software, and had only a minimal grasp of IT principles.

While there will always be a need for instrumentation software, my specialization forms an ever smaller fraction of the overall software development landscape. Which has made job searches increasingly more difficult, and interviews more frustrating, as fewer HR people know how to specify and fill positions for instrumentation developers.

That's not to say there's no hope!  The explosion of the Arduino and now the Raspberry Pi into the hobbyist market bodes well for a healthy population of embedded/real-time system developers.

After 30 years I'm finding that choosing to stay out of management has made me a relative fossil among the applicants for instrumentation/embedded/real-time developer positions.  Rather than beat my head against the wall, I've instead decided to take my skills and experience in a new direction: I'm going to become a STEM teacher, and see how many folks I can convince to become the next generation of engineers!

The Path to Becoming a STEM Teacher.

Those who've seen my recent Facebook posts know I finally decided to become a triathlon coach, with the intent to focus on beginners and data-driven coaching.  Literally days after making that decision I received a newsletter from Code.org mentioning that EnCorps was recruiting STEM teachers from the sci/tech community.

I immediately thought: "Woah. Teachers get summers off.  I could coach more during race season!"

Then I thought about the state of my career, and that it may be time for a major change.  Over the past few years I've been encountering significant ageism now that I've become an "older" engineer seeking permanent or contract work. It's certainly not as easy for me to find new business as it used to be!  I call it ageism because I know for a fact my skills are relevant in the market: Some recent job descriptions look as though they were pulled from my resume!  Yet I'm not getting many interviews, not even phone interviews.

EnCorps gave me a phone interview last Monday, a few day after I completed the online application, and they've scheduled an in-face interview for next Wednesday.  The feedback I've received from the EnCorps SoCal recruiter has been totally enthusiastic, despite the fact that only about 18% of EnCorps applicants make it to the classroom.

Still, it is nice to be wanted. I had almost forgotten what it felt like.

I started down this path primarily out of curiosity. I'm getting more excited with each passing day, but also more aware of the huge amount of work ahead and the great responsibilities to come.

But why leave engineering?  It is what I've loved doing for over 30 years, and it forms a core part of my identity.  It is also been the most fun I could ever imagine getting paid for!  Being an engineer has been the perfect fit for me.

I've had to look very closely at my motivations and the downsides.  It could be that I'll be a terrible teacher, though I honestly believe I'll do fine. I've had several teaching experiences during my career, and they all turned out well.  I greatly enjoyed them, and my students did too.

Truth be told, I have hobby projects that will keep me neck-deep in hands-on engineering for years to come. Many of these projects were started so I could learn and apply new technologies, both for fun and for professional development.

I've also been advising crowdfunding projects, participating in several science and tech forums, and answering questions on some of the StackExchange sites.  Which, when you think about it and squint just right, could look a bit more like teaching than engineering.  I wonder if I've been on this path for a while, and simply failed to see it for what it was?  Perhaps, but I suspect it's simply how I like to fill my time. Still, it is relevant.

I'm moving forward with a career switch to STEM teaching.  Wish me luck!

Failure Modes for Self-Driving Cars: It's All About "Situational Awareness"!

There has been lots of recent discussion concerning when and how self-driving cars should return control to the driver, and how this process should work in a variety of scenarios.

I won't be discussing truly autonomous vehicles, which by definition have only passengers, not drivers.  Self-driving cars, in my use of the term here, always require the presence of a licensed driver, and completely support operation as conventional cars.  I'll use the term "autopilot" (as in the aircraft and Tesla sense) to more clearly distinguish "autonomous" from "self-driving" vehicles.

The first and most important scenario concerns the rapid and total failure of the autopilot system, where control of the vehicle suddenly shifts to the driver.

Even if the car has independent and hardened emergency systems to help out when the autopilot ceases to function normally (either because of damage or exceeding its capabilities), there is always the (low) chance that such backup systems will all fail when the autopilot does.

I remember well the first time I bought an older luxury car with all the nifty powered accessories.  It was also my first car with working A/C.  I was so proud of it, as it was a huge step up from the junkers I had been driving and endlessly fixing.

Late one evening while driving on the highway at speed, the battery cable fell off and hit the body, shorting the entire electrical system to ground.  (I later found the entire battery post had fallen off!)

The headlights and dash lights went out, and I initially felt blinded.  Cruise control cut-out and the car started slowing.  I had no power steering and the car started drifting out of its lane.  Gas pedal response was sluggish and the engine started running rough.  The automatic transmission wouldn't shift automatically.

It was only my experience with a series of junker cars that saved me.  While I never before had everything die all at once, it wasn't rare for one thing or another to go wrong for me during a drive.  Pretty much every car system had failed for me at least once.  In the back of my mind I was always running sub-conscious "what if" scenarios, and adjusting my driving to avoid traffic situations that could make a failure worse.

I firmly gripped the steering wheel and started "driving by Braille" while my eyes adjusted.  Fortunately I was in California, which has "Blot's Dots" bumps and reflectors glued between the lanes and at the outer edges. While the headlights of the cars near me helped, it still took about a full second for my eyes to adapt to the metropolitan sky glow well enough to see the road immediately in front of me.

I had no brake lights; I knew the greatest hazard was the cars behind me and next to me, so I didn't want to slow down too quickly.  I applied some gas and tried to get the transmission to shift (it did respond to manual input).  Only after I reached the shoulder did I apply the brakes and come to a complete stop.

Now, let's instead say I was in a Tesla, with full Autopilot Mode active, when the battery pack suddenly became completely disabled (not really possible, but work with me here).  This raises two main questions:
1) What parts of this scenario can or should be handled by the "dead" self-driving system?
2) How can the driver be kept ready to cope with the "total failure" situation?

Let's discuss the first one first:  Before we can trust a self-driving system to self-drive, we must first trust the self-driving system to exit self-drive mode and bring the car to a safe stop, even without driver help.

This means the car will likely need two separate systems:  The self-drive system, and a separate emergency system that monitors both the self-drive system and the driver and on its own can safely bring the car to a halt.  This emergency system must:
- Have its own controller, wiring and power source, separate from the rest of the car.
- Be able to take steering, propulsion and brake control away from a failed self-drive system.
- Work long enough to get the car from speed down to a safe stop, preferably at a safe location.
- Allow the driver to take control at any time.
- Encourage (not force) the driver to take control when the emergency system itself lacks control of steering and/or brakes (electrical regen and/or mechanical).

There are many other things such an emergency system must do, but they are at a lower priority than the above.  For example, such a system should also snug the seatbelts to ensure the driver is in the right position to take control and (worst case) be ready for airbag deployment.  The system should also pose minimal risk to other traffic by doing its maneuvers in ways that enable other drivers to safely respond (avoid causing accidents).

Such systems already exist and are in common use in other industries.  For example, virtually all industrial robots have independent safety monitoring systems that prevent the robot from harming itself or its environment, especially people nearby.  And NASA has for over half a century pioneered such emergency control systems for aircraft and spacecraft.

Now let's look at the second situation: Even the best emergency backup systems can fail.  Fortunately, old technologies (and existing regulations) ensure the driver can establish emergency control over steering and brakes.  This situation now becomes ensuring the driver is ready to take control.

The emergency backup system is a form of "active" safety.  Before digging deeper, let's talk about "passive" safety systems:  When all else goes wrong (but no collision has occurred), the mechanical systems themselves can provide safer vehicle behavior.  The most familiar examples of this are:
1. The mechanical design and construction of the steering system, where the wheels gradually come to center when the driver (or autopilot) is not exerting direct control.
2. The design of the accelerator and brakes, so that neither engages without the driver (or autopilot) exerting direct control:  The vehicle passively glides to a stop when active control is absent.

Clearly, every self-driving car must preserve all existing passive safety features.  That's actually a significant design complication, that the self-driving actuators by default are safely inactive whenever power or positive control is removed.

Very few drivers today have any experience with unreliable cars.  Cars built over the past 30 years have amazingly low failure rates (assuming you promptly handle all recalls), leading to exceptionally high reliability and driver confidence.

Can we maintain driver confidence, and create such confidence for autopilot systems, while simultaneously keeping the driver ready to take over during a total system failure?

Here's where we finally discuss the title of this post, "situational awareness".  In this case, situational awareness means the driver is continuously informed about, and consciously aware of, the status of the car and the state of the current driving environment.  This level of awareness must especially be maintained while in self-driving mode, when the driver may be focused on other activities.

It is important to understand that awareness is always changing; it fades with time and must be actively refreshed.  The best possible awareness comes only when in full manual control: In all other fully- or semi-automated driving modes, the driver will inherently and inevitably have a significantly reduced level of situational awareness.

The goal then becomes keeping the driver at a "good enough" level of situational awareness that will enable prompt switching to the full, manual control level of situational awareness.

Increasing our level of situational awareness is perhaps one of the hardest tasks for the human mind to do in real-time. It involves not only refocusing our senses, but also activating our musculature, and even changing our posture.

Here's the worst case, the stuff of nightmares: Imagine being asleep, then waking up in the cockpit of a race car in the middle of a race.  Your ears are filled not just with the noises of the car, but also of the other race cars and maybe even the crowd.  Your eyes are assaulted by the brightly lit race course filled with weaving cars, as well as a dash filled with a huge number of gauges.  Your hands feel the shake of the steering wheel as you compulsively tighten your grip.  And who knows what your legs and feet are doing!

Clearly, the first thing is to not make the situation worse.  There must be no visual or audible distractions that get in the way of dealing with the situation: Alarms must be very noticeable, but not shockingly loud or bright.

OK, so that's the worst case when a loss of autopilot happens.  How can we best be prepared for it?  And do so without removing the benefits of self-driving?

Well, obviously the driver must be awake.  Not only that, but the driver must also be alert enough to take control.  The only way I know of to positively ensure this with any degree of reliability is by interactive testing (not via passive monitoring, as others have suggested).  The driver must occasionally take actual full control of the vehicle, or at least demonstrate a precisely equivalent level of readiness by other means.

More importantly, this is not just about manual driving: It is about ensuring the driver is capable of smoothly and safely transitioning from self-driving mode into manual driving.  It's about the process of taking control, a precursor step to to the process of manual driving.

To me, this means the modes of the autopilot can't be simply "on" and "off".  It should have the initial mode of "taking automatic control" and the final mode of "surrendering automatic control".  This last mode should, to the greatest extent possible, also be part of the emergency system.

If the driver can't successfully follow the "surrendering automatic control" process, the system should not turn control over to the driver, and should instead perform an alternative action (continue driving, pull over safely, etc.).

Writing Documentation That Doesn't Suck

I've often had to write manuals for the products I've developed. The Technical/Maintenance manual is easiest (because the audience is technical), and the User/Operations Manual is by far the hardest (anyone can be a user).

Like many engineers, I took the minimum number of required writing classes.  So it was not a huge surprise that my initial attempts at product documentation were terrible.  Over time I finally became "not horrible" at documentation, and the main path to success was to avoid saying too much!

There are many technical writing guidelines online, but I find most are too narrowly focused to be of general use. A few simple guidelines are generally enough to avoid documentation disaster.

Here are some guidelines that have served me well:

• "Don't write so that you can be understood, write so that you can't be misunderstood." William Howard Taft

This is partly about getting inside your reader's head, and partly about getting out of your own. It is all too easy to write for people who are near-clones of yourself, and forget the wide range of other folks on the planet.

It's about making your writing as "simple and obvious" as possible. Avoid long-winded explanations when a couple short, carefully-crafted sentences will do the job. That said, always use however many words are needed to make each point clearly and concisely.

Important things may need to be said more than once. What I typically do is "say it once", then show an illustration, then explain the illustration, and finally summarize what was just done (what success looks like).

• Have some "fresh eyes" available.

Given that we can't understand all possible readers, we must remember that we only truly care about the first-time reader. That means at least some of the folks who review our work must also be as close to a first-time reader as possible.

In particular, this means it must be simple and easy for actual users to provide feedback on the manual itself. Encourage each customer to print and mark-up the instructions, and tell them how to get their input back to you (email, forum, etc.).

• Include a glossary.

It is way too easy to use too many technical terms, and too hard to get rid of them. Having a glossary and always keeping it current is a great way to track specialty terms and language.

• Don't get tied down to a Table of Contents: Make it the last thing you generate.

Too many folks start with a Table of Contents as the plan for the document. This is backwards! The document should have whatever organization and structure it needs to get its job done, and the flow is expected to change with time.

That said, it is important to have a "ToDo List" for the document, a detailed set of goals for what must be included and not left out.

Of course, organization is needed, but primarily at the lower levels:
o What is the purpose of this step?
o What tools and parts are needed to accomplish this step?
o What things must I do?
o How can I verify that I did it correctly?

• There is no such thing as too many good illustrations.

However, there is such a thing as too many bad illustrations! The old saying "A picture is worth a thousand words" isn't totally wrong, but having a picture doesn't mean words aren't necessary. Illustrations should add context and meaning to words, not replace them.

For something like kit assembly, there are going to be situations that words can't express in an understandable way. This is when illustrations matter most, so take the time to create lots of candidates and choose the best. Try to avoid the "one and done" attitude to images or drawings.

• Layout matters! But not until close to the end.

One important goal is to not force the reader to have to flip back and forth between pages to understand what's going on. Text mixed with images? Images and text in separate columns? Size? Pagination? These are all important to the reader, but not unless and until the needed information is already present in the document.

• Documentation is really about "teaching", not "telling".

The user has goals, and the documentation must ensure the user will meet those goals with minimal confusion, and minimal need to ask for help. For kit assembly, the initial steps should train the user to become a good assembler, not merely get things put together.

Not all of us learn in the same way, and there are a number of ways by which we learn. These ways are called "learning modalities" (or "learning styles"), and while we all have access to all them, some work much better than others, and which ones do best will vary between individuals.

It is often necessary to say a thing in different ways (words, pictures) in order to engage multiple modalities. It is also important to help the user sharpen the modalities that will be most useful, and that's where training comes in. Take time at the start to build the skills the user will need before making use of them. Even the fundamentals matter:
o What is an "M4 screw"? Is a screw different than a bolt?
o What does it mean to "tighten a screw"? How tight is tight enough? How tight is too tight?
o What does it mean to "crimp a connection"? How can I tell if I did it right?