Advice to software vendors
Mar 13, 2011I am regularly frustrated and annoyed by “Enterprise” software vendors who have never deployed one of these Nimitz-class systems outside a VM running on their salesperson’s laptop. Here are some hints on getting your software into the Proof of Concept instead of running aground:
- Components go into packages Think of your software in terms of components- core, recommended, optional, client, GUI, docs, etc.- and package that way. I don’t want to manually disentangle a couple of gigs to get the feature set I need. This leads to…
- Package documentation separate from binaries You get points for having documentation, bonus points if you document your DB schema, double points if the docs bear a passing resemblance to the actual shipping product, but please put the PDF’s, the man pages, the knowledge base and that copy of the website into a separate installation. I really will Read The Fine Manual, I just don’t need to have that whiz-bang local copy of your multi-product infocenter in with binaries. Which leads to the next point…
- Separate out third-party code If you require a web server and provide Apache, great, put it in its own module. If you require, for example, a JVM, put it in its own module. If you include third-party libraries, put them in all their own module. Don’t shovel at me the entire stack of http server, JDK and out-dated versions of half of the Apache project.
- Fancy installers must be optional It’s possible that some of your customers’ IT people care barely wipe the drool off their chins, but I should not have to reverse-engineer your installer. Put the GUI in front of simple, standard tools and formats. Better yet, provide a second console-based installer script written in- pick a language- shell, Perl, Python, TCL, REXX, whatever makes you happy. On a deployment of any size, the installation will be done in anger twice- once in the test lab, once for deployment. Your installer will not be run by hand on ten thousand systems. If it does need manual attention, it probably won’t get past the first time. This leads to the next two points.
- Use a package format accessible with common tools If the
platform doesn’t have a native package system (
pkg
,deb
,rpm
,msi
, etc.) use the standardtar
,gzip
,bzip2
orzip
. 7zip and LZMA is fine. On Windows usezip
,cab
,msi
andsfx
. Go old school Unix and usecpio
andcompress
if you like but don’t force me to use the installer to get at the contents. - Don’t assume anything about your system privileges, the filesystem
or paths One size does not fit all. You may not have rights to
scribble in arbitrary directories. You may not be run as root. You
may install in a staging area with different paths than those found
at runtime. Common binaries may not be found in
/usr/local
as you expect. Assume that paths will always be the maximum of POSIX, XOPEN orsys/syslimits.h
maxpath, UNC max length, etc. Always give me a choice and leave enough space for the locally correct answer. - Don’t strip binaries When, not if, your code fails spectacularly I want a useful core dump. So what if the symbols take up room on disk, for any contemporary system there is plenty of space. For Java, also don’t run it through an obfuscator. If necessary, provide a second set of binaries with symbols and let me choose. Don’t tell me after I send you a 3.9GB core that there are no symbols and it will be a few days before your build team can get me an unstripped release.
- Design with the debugging in mind Leave it in the release. If a
flag or environment variable is set, emit debugging. Points for
emitting it to
STDERR
, deduct two points for emitting it to bothSTDERR
andSTDOUT
. Deduct ten points if it lacks timestamps. And speaking of timestamps, deduct twenty-five points if your run-time log lacks them, deduct fifty points if failed assertions lack them. - Include an API I’m sure the dev team thinks the software is perfect- or as close to perfect as the release date permitted- but you can not forsee every possible use of your software. Extra points if it’s in C, deduct a half point for C[]{.underline} (no change for Java or for Perl or Python as I can make my own bindings if you give me a C API). Bonus points if there are callbacks or hooks exposed in the product, I’ll want to use those to change its behavior or implement something you don’t (ex. security). The API should be the same one the tools you provide use and it should access all of the product functions. If it’s crippled, it’s worse than no API at all because it will waste my time.