Internet: Redundancies, Backups, and Spares

Field Reports

Written by Jerry Stern

There was a power failure here a few months back. 14 hours with no power, and then there were lights outside my window in the dark, and there was a power company truck with cherry picker, a portable lighting truck, and cable truck, all lined up at the power pole, and working in cold rain at 3am. And then the next morning, a fire on same pole took out the other leg of the 240 volt service, just not the 120-volt service I depend on here. I thought I had my communications reasonably well-diversified; now, I still think so, but I made changes, and will consider more.

There was a time when I had no problem turning off the internet, and replying to emails a week later, if that’s when I got back to my desk after a vacation. That was 15 years ago; the world has gotten considerably faster since then. Now, if my business is offline, I can’t monitor websites–can’t really edit them offline because of all the Content-Management Systems (CMS), can’t get to email, can’t get to voicemail, can’t do much at all.

To protect myself from outages, I have backups and redundancies. My business phone is a traditional land line, sometimes called POTS as an acronym for ‘plain old telephone service’, but my personal phone line is from the local cable company, where it is half the cost, and just having it results in a discount on my internet service, so the net cost is that it reduces my bill by $8 a month to have it. OK, the business line stayed up in the outage; cordless phones failed, but there’s one corded phone on each floor of the house. The personal phone line failed, despite having built-in battery backup and being plugged into an Uninterruptible Power Supply; when the system dies at the pole, there’s nothing to do.

Internet is another matter; when power came back on, the internet and the private phone line stayed down. The cable company was able to reset the phone remotely after I called in on the land line, but Internet was still down, and they scheduled that repair for four-days out. In typical clueless-cable fashion, they neglected to find the regional outage, which was fixed some 12 hours later, but still, I had no internet, and a promised 4-day outage, on a Monday of what was going to be a very busy week.

Backups Chosen

I added a smart phone with a good data plan. That gives me options that don’t rely on any cables coming into my office, either internet or power. It’s not a fix for every problem in an outage, but it’s a start. Next: How to filter spam on a smart phone. (to be continued…)

Facebooktwitterredditlinkedin

Book Review: This Little Program Went to Market

Reviews

Now here’s a book that appeals to the microISV. This Little Program Went to Market, by by Annette Godtland, takes on the rather large task, for an encyclopedia, of teaching the reader everything they need to know about creating software and selling it on the internet. For one book, it’s a somewhat ambitious goal.

Here’s the subtitle: Create, Deploy, distribute, Sell, and Market Software and More on the Internet at Little or No Cost to You. That’s a strength and a weakness–that subtitle would take several thousand pages to cover properly, and at 546 pages, the book is nowhere near that heavy–this is a good introduction, but hardly all that’s needed. There are five parts:

Part I: Create a Program. Godtland chose Java as a sample language to create a classic ‘Hello, World’ program or Java applet. There are details on where to get tools, source code examples (also downloadable from the book’s website link), and all the steps needed to write a program, but this section is not a programming manual; it’s enough to get started, before looking for more elsewhere. Most programmers looking to sell software online are already programmers, and will just skim these four chapters.

Part II: Deploy a Program. That’s creating a help file, a program icon, wrappers for Java applets, piracy protection (but see below), trial versions, an installer, and testing. That’s 10 chapters, and a lot of information. The Install chapter is a better tutorial on Inno Setup than is easily found online.

Part III: Create a Web Site, Distribute a Program. Covers web site creation, hosting, HTML standards. Four chapters, and again, basically an introduction.

Part IV: Sell a Product. Covers taking check orders, credit cards, PayPal, creating keys, filling orders, adding a shopping cart in Paypal, but doesn’t cover using ecommerce partners other than Paypal.

Part V: Market a Product. Search engines, shareware versus freeware, marketing, and web statistics and logs. The definition of shareware is interesting, taken from an online dictionary, but it’s something out of the 1980’s.

This is a good book for new software publishers. It’s like the notes that a first-time attendee to the Software Industry Conference would make–pages and pages of information that’s hard to find all in one place, and information overload is possible. There’s lots of information, and good coverage on the technical topics. The writing is clear, the code samples are formatted nicely, and opinions are generally labeled as opinions, not as absolutes.

However, there are gaps here. The ‘Piracy Prevention’ section recommends code obfuscation, with no methods for encryption or self-checking a distributed executable file for alteration. Code-signing is mentioned, but dismissed as too expensive. And the legal issues of copyright are just plain wrong–there’s a statement that “Nothing need be registered anywhere” and no mention of how to go about registering a program at www.copyright.gov. The marketing section matches the typical microISV pattern–it’s weak.

All that said, this is a very large topic for a book of any size. The gaps are best filled-in by a membership in the Association of Software Professionals and a trip to the ASP newsgroups and archives, and the book will provide a very good starting point on dozens of topics important for launching a software product online.

Jerry Stern is the editor of ASPects, the ASP’s Coordinator of Anti-Spyware Operations, and is online at www.pc410.com.

Facebooktwitterredditlinkedin

Documentation: From Programs to Products

microISV How-To's

by Jerry Stern
PC Tech at PC410.com

OK, great program. Now, what’s next?

There are some basic differences between a program and a product. Most software developers understand many of these instinctually. As a program becomes a product, on-screen messages are made more specific. Screen layouts are more polished. Errors are trapped and result in plain-text messages that help resolve problems, or even-better, are user-proofed so that incorrect procedures still create great results.

But that’s mostly programming code and artwork. The biggest difference between programs and products is the documentation. Specifically:

  • Sales pages and advertising.
  • The user manuals.
  • The instruction books.
  • Help files.
  • Screen shots, slide shows, and videos.

If these are missing or are incomplete, the product won’t sell like it could, or at all.

There are several basic and common errors in documentation for modern software that aren’t quite product-ready:

  • Not writing documentation. (You know who you are…)
  • Or combining the various types of documentation, and skipping over a basic need. There are five types of documentation. A real product must have all five types, and while they can have minimal overlap, all basic types should exist for nearly any software product.

Five Types of Writing

Before writing any of the documents below, stop and choose a writing style that will work through that entire
task. Changing style isn’t about formality or slang–it’s about the basic reason for writing. The basic writing styles are:

  • Exposition: Writing to inform, to explain a process or an event or an object. Your main help file should be mostly expository writing.
  • Persuasion: Writing to persuade. Frequently includes classical rhetorical techniques to bring the reader to your point of view. Applies to press releases and other sales-related documentation. Classical rhetoric is the most difficult writing style; use it with caution and a light touch.
  • Descriptive: Writing to describe and define what a product looks like and how it behaves.
  • Narrative: This writing is common in fiction, for telling about a sequence of events, but it can also apply to a wizard-style product interface.
  • Creative: Novels, plays, poetry, stories. I’ve seen these used well in product documentation, but only once in a utility program. Needed in many games, but avoid them in most other products.

The majority of your product documentation should be exposition or descriptive writing, and your sales documents should be persuasion with a little rhetoric. Overlap them more than just a little, and your document will lose focus and effectiveness.

Five Types of Documents

Here too, try not to overlap the types of documents below.Breaking these into separate projects makes them easier to write, easier to understand, and more effective. (Or, for the software types among us: Less likely to result in a tech-support contact.)

Motivation

These are sales documents, your web site, press releases, your advertisements, promotional emails, logos, artwork. These include the sales pitch, the classic AIDA steps of Attention, Interest, Desire, and Action. In short:

  • Attention: Something not routine. Something that stands out. Unique. Maybe bizarre, if your product isn’t a
    business application. Anything to get potential purchasers to look.
  • Interest: These are the product descriptions, written as benefits, not a feature list. It’s about what the user can create, and not about the tools and instructions.
  • Desire: Why they want it. Or will. This is where the “Ooooh-Ahhhh” goes. The excitement should be building.
  • Action: Call for action, go for the closing, ask for the sale. Buy now!

There’s a reason that sales letters from the very largest product sales companies are four pages long–they’ve tested the letters, included every step for attention, interest, desire, and action, and they know it works. But that format is best on paper or television. Adapting a non-sequential web or software version will take more work. A video or demonstration may be a better approach to building the AIDA steps.

Instruction

Getting-Started Guides: These are the most-left-out documents in modern software, and the most likely to prevent a technical support call. These describe basic screen layout, functions, what always must be done first, and what the words on the screen mean in the context of just this product. Instructions are meant to be read by new users, not word-searched, and must be organized in a logical progression:

  • What does the product do?
  • What can my final project or result be?
  • How do I get started?
  • What’s the basic navigation through the program?
  • What’s in every use of the program, or what steps are in every project?
  • And finally: A description of where the rest of the help is, in the tutorials, demonstrations, and references.

This documentation should always be included in the product installation. It can be duplicated online for sales and Search Optimization purposes, but it’s so basic to using the product that it should always be included in the product in some form.

Tutorials

This is how to work through a series of introductory steps and learn the basic operations of a product. Tutorials are for new users. These may be slideshow format, or help files, or videos. These will frequently include building a project of some complexity, by starting small and working though many continuous steps to add options to the project. These are typically numbered, and build on each other to bring the user to a level of mastery, step-by-step.

There’s a trick to tutorials: keep every step strictly in the sequence that the user will take them on-screen. It’s “Go to the File menu and click on Print” and never “Click Print in the File menu.”

Tutorials can be included directly in the product, or online. Frequently, the best approach is to include basic tutorials on program layout and project steps within the help file or a ‘Getting Started’ popup, and include a link to bigger and newer tutorials online.

Demonstrations

These are step-by-step guides, frequently done as animated slideshows, for a single and specific product task. Demonstrations are for users already familiar with the basic operation of the product. These show how to do processes or projects, and leave out no steps. These can be used as needed, in isolation, and should not build on other demonstrations.

Demonstrations, like tutorials, can be within the program, or online, or split, with the advanced topics online. But tutorials are sequential and introductory, while demonstrations are standalone and project-based.

Reference

This is what programmers want. It’s the notes for the advanced features, the guide to doing complex items, and the ever-growing tips and tricks list. This works well in a Wiki format, or a searchable knowledge base. It’s not the material that most users of the product would memorize, or must know to use the most basic functions of the product.

Knowledge bases and Frequently-Asked-Question lists are mostly online. Basic FAQ topics should move into the
Instruction guide during revisions to the product. Advanced topics should usually remain in the knowledge base.

Hiring a Professional Writer

Can documentation be outsourced? Some can, but not all. If the programmers have started the reference documentation, and created a basic tutorial that a writer can follow (in any form, including a one-on-one lesson), then a writer can convert that tutorial into a form ready for a general audience, and start building the tutorials and possibly some of the basic demonstrations.

More mistakes:

Using marketing documentation as an instruction book. Selling is not teaching.

Using a feature list as a press release. Features don’t sell, and bullet lists don’t read well. Selling requires sentences that promote benefits. If your press release is made of lists, it’s not a news story, and won’t be published by any media companies.

Interviewing yourself for press releases or product sales. No, wait–are you Steve Jobs? This rule may not apply, then. Everyone else–don’t quote yourself in your press releases or on your web site.

Mixing tutorials with demonstrations: A guided tour is not a step-by-step procedure; combinations will become
large and overly complex. Again, tutorials are sequential, and demonstrations are for single tasks.

Using an online Knowledge Base or a Wiki as a help manual. These are for problem solving, and can’t replace an introductory set of lessons, which should include a tour, terminology, and getting started with some basic projects.

Consistency

Finally, use the same terminology everywhere. A folder is a folder, and not a directory. A picture is a picture, not an image. Both may be correct, but pick only one, and then stick with it.

It’s great to have a glossary that includes mentions of “This is also known as …”; that helps the search function of your help (or Google, for online help) to find entries when users look for help on topics that you don’t have listed in the menus or the help contents. But overall, be consistent-–this is more about clear communication, and normal writing rules that say not to overuse single words do not apply here.

Keep parallel sections of the documentation similar. Maybe they should all start with a definition, or a screen shot, or an image of a finished project. Pick one style, and stay with it.

Finally, read it all out loud. Well, everything except the reference materials, anyway. You’ll hear errors in your writing far more easily than if you see the words on-screen. And you’ll notice that sections of your text belong somewhere else, and that leads to better organization and betterproduct documentation.

Jerry Stern is the editor of ASPects, the ASP’s Coordinator of Anti-Spyware Operations, runs Startupware.com and WorPerfect.org, and www.sciencetranslations.com.

Facebooktwitterredditlinkedin