Good Bug Reports

Bugs happen.  It doesn’t matter how much experience you have, or how much you test your code, a user will do something that you didn’t expect and your application behaves improperly.  Perhaps it throws an exception and reports it to the user and continues working.  Maybe your application quits on exceptions.  Either way, you have an unhappy customer that is reporting back to you.

“It’s crashing,” is a common phrase I hear in the Xojo forums and from our own users.  So the first question I usually have is “is it really crashing or is the application reporting an exception?”  The difference being, of course, one is controlled by me and the other is the application goes *poof* and there’s nothing controlled about it.  With the former I usually have some data that can help me figure out what’s going on and the second is a bad sign that it might be a plugin or library issue that I’ll have to track down.

What is their operating system and version?  

It’s important to know if they are running on Mac, Windows, or Linux and what version it is.  For Windows and Linux it’s important to know if it’s 32-bit or 64-bit.  You may end up having to send them instructions to determine what version they’re running depending on the end-users skill level.

What version of the Application/Library/Control are they using?

Applications are relatively easy to get version numbers from since the user can get this from multiple locations (usually).  Controls and libraries are a different matter and you, as the developer, should make this easy to find with documentation and constants in the code.

We’ve all had an email where a disgruntled customer says, “It doesn’t work!”  If you have multiple products this makes for an awkward return email asking which product they’re actually talking about.

Can they replicate the problem?  If so, what are the steps?

Customers often think that simply telling you about a problem is good enough.  Sometimes it is but usually I need more information.  The more detail the better.  If it’s a sequence issue I will sometimes ask for a video showing it in action.

Can they send you the error log?

If you create error logs it is helpful to get those.  To get the error Stack of an exception is useful and can sometimes tell you exactly what to fix if you’re lucky (especially with small/short methods!).

You may have to tell the user not only where they are but how to get the location.  Getting to the Application Support folder on Mac and Windows isn’t hard but it’s also not easy.  On MacOS the users Library folder is invisible by default.  On Windows this location is buried multiple layers deep.

Can they send you an example project or file?

With developer products it’s handy to get a small example project demonstrating the issue.  I can’t tell you how often simply asking for this solves the problem because they find their own mistake.  Even if it doesn’t you now have a good example project demonstrating an issue you didn’t know about!

With applications and utilities getting their data file is good.  There is nothing like working with real data to discover issues.

Users aren’t often helpful when it comes to asking for help with your products.  What other things do you ask customers when dealing with bugs?

Chrono-Optimism

At the XDC Keynote a few weeks ago Geoff Perlman said they’d no longer give target dates for new features.  Instead they’re going to say what’s a ‘priority’ and what’s ‘important’.  Software projects are often big and complex and it’s very hard to estimate the amount of work involved with a new feature.  “Happiness is all about having expectations met,” said Geoff and I think it’s fair to say that Xojo has typically been overly optimistic on when a feature is going to ship (much less when it’s going to be usable).  So instead they’re going to stop predicting when a feature will be released.

If you hear them say it’s ‘Important’, it’s something they’re seriously looking into.  It will be in the product in the not too distant future.  A ‘priority’ means it’s either in active development or will be shortly.  The Rapid Release Model is still in play which means we will still get releases three or four times a year.

In one sense I’m disappointed that they’re not going to give us any timeframe for new features.  I really want to know when Web 2.0 is going to ready for testing as we have a number of projects in development or about ready to start development that it would be really nice to know if it’s a 90 day, 120 day, or longer window.  Android is a nice to have feature, but since I’m not doing much mobile development it’s not that important to us, but I can see how for some it is a huge need.

In another sense I understand why they’re not going to give us target dates any more.  They’ve missed every projected release date that I can think of and I’m going back a lot of years.  It was about a year ago this week, in Berlin, that Geoff said that Android would be out by the end of 2017 when the reality is that we’ll be lucky if we see it by the end of 2018 (that’s just a guess on my part and having having been around a long time).  I would love to be wrong on that guess but it’s a new target that involves a ton of compiler, framework, and IDE work not to mention the need for Interops (a dependency) to work well.

Estimating a project is not a science.  You’re asking software developers to take a wild guess at how long a big feature is going to take.  When you make that initial guess you don’t know that replacing this small piece of code will affect this much larger piece of code over here.  Or cause this other piece to not work right thus forcing you to redo that other piece too.

In some respects creating a new project is considerably easier than replacing code.  In new projects you’re touching everything anyway but subconsciously you’re holding most, if not all, of the work in your mind and you shape it as you go.  Big, existing projects, or OPC (Other Peoples Code) projects, are considerably harder since not only do you have to read the code but also figure out the intent of the code and second guess what the original developer was attempting – not always an easy task.  I’ve never seen the code for the IDE but I’d imagine dozens of people have worked on it over the years with varying degrees of competency and coding styles.  So whatever work you do you have to read, interpret, change, and test to make sure it doesn’t break something somewhere else.  Tack on multiple environments and targets and it’s a herculean task.

I’ve spent the last four years working with my son’s FRC robotics team (team 1982) as the programming mentor.  They have six weeks to design and build a robot to a very demanding set of specifications before they crate it for competition.  These 120 pound robots are relatively complex and I’ve seen it time and time again where the kids have ‘Chrono-Optimism’ in what they believe they can get done in after-school meetings (some with mentors present and some without) and on Saturdays.  Granted, they spend a LOT of time working on the robot, but they’re just kids and most of them have never done anything like this before.  They don’t know what they don’t know and most years they’re scrambling just to get a working robot.

This year, the group of seniors really thought about what they wanted to do.  They knew it would be challenging, but they decided to change their build process and use a more modular hardware design which meant new gear boxes, wheels, framing, etc.  They also decided to build two robots which, for a team that’s never done that before, was …ambitious.  Then they decided that they wanted to go two regional tournaments.  Again, ambitious for a team that’s never done that.  From previous years they also learned something else:  they were attempting to design too much on the robot.  If there were three major tasks that a robot had to accomplish they couldn’t do all three with the resources and experience they had.  They couldn’t change the amount of time to build the robot so they changed the one thing they could – the scope of work – and made the robot simple and sturdy.

The Universe works in mysterious ways and has ways of throwing a monkey wrench into the best of plans.  The last day of build season this year happened to be a day off so the plan was to have a twelve hour work day to finish the robot and test.  Instead, Kansas City had a snow storm which cancelled all school activities.  The robot was not mechanically complete and not functional programming-wise.  The kids were devastated.  But there is a silver lining to their story.

The robot was crated away and couldn’t be worked on for weeks, but the second robot allowed them to work on the programming and driver training.  The modular design allowed them to plan the work they needed to do at the tournament before it started.  The simplicity of the robot meant that the work could actually get done in a short amount of time before taking to the field.

To conclude this story (because I’m bragging now), the team won their first tournament which qualified them for World Championships.  They were the eight seed alliance captain in their second tournament.  At the world championships, they finished 42nd of 67 teams, but were picked as part of the 6th seed alliance.  They won in the quarter finals and ended up getting to the semi-finals where they were defeated by the alliance that went on to be third in the overall tournament (out of 400 teams).  All because they examined their past behavior and decided to change it.  They knew they were bad at estimating and changed their expectations.

I will give credit to Xojo for realizing that, like most of us, they are Chrono-Optimistic in their estimates, and decided to change how they communicate to their customers.  As Geoff said, part of their job is setting expectations and they’ve been really bad at it.  It’s clear that they said ‘estimate’ and we heard it as a ‘promise’ which is partially on us.  So now we have what’s a ‘Priority’ and what’s ‘Important’.  I don’t know if this will help them, or us, in the long run but it will be different and I’m willing to play along for now.

What do you think about this change?  Negative, positive, or neutral about it?

Consulting Red Flags

The one absolute truth about consulting is that if you’re not working you’re not making any money.  The corollary to this truth is that you are either 100% busy or 100% not busy.  This is especially true if you are a solo developer.  It is very hard to turn down projects when they come your way but I’ve found that there are times when you should.

I get it.  Really, I do.  If you’ve been idle for longer than you’d like and money is starting to get tight ALL projects start to look good.  Don’t take the project because you need the money.  Take the project because it’s a good fit, it’s interesting work, and you think the client will be a good partner.

In the world of make-believe this is the way it should be.  In the real-world you don’t always have those options.  Plus, it’s really hard to figure out if a project is going to be a good one or not.  Here are some of the red flags I’ve come to recognize in fifteen years of being a Xojo consultant.

Other Peoples Code (OPC).  Code written by someone else is always a red flag.  We write code a certain way and if any of our team work on it we can rest assured that certain things will be done (naming conventions, comments, etc.).  No such guaranty with OPC.  It’s way easier to start from scratch but with most OPC projects you don’t have that option.  So you start with a level of uncertainty and having to decipher not only the coding style but often times the intent of another developer.  Learning someone elses code stinks.

Project complexity.  When I’m asked to join an existing project I try to look at how complex it is.  If it’s really complex I hesitate because I know it will never get less complex.  In many cases the original developer tried to be clever to solve some (real or imaginary) problem and while solving it completely overlooked a much simpler way of doing things.  Plus, if it’s not one of your core competencies it might not be a good fit anyway.

Another item under the project complexity red flag is excessive amounts of documentation.  From experience, most projects can be summed up with a page or two of high level description and then a dozen pages of important detail.  When the client sends you a very long document with high levels of detail you might be getting yourself in other your head.

Of course the flip side of that is clients that send you a paragraph or two of their idea.  In those cases we have to draw more information out of them, and depending upon the size of the project, we might actually charge them to write their specifications for them and let them get some competitive bids from other developers.  I think the lack of detail says they haven’t done enough homework on what they want and need.

Toxic teams.  Another issue with joining an existing project is trying to figure out if the team is toxic or not.  The existing developers will always have their own habits and you, as the consultant, need to try and match theirs.  What if those habits are silly?  I’ve seen teams that require a comment for every line of code.  I’ve seen some teams that disdain any comments under the guise that code should be ‘self commenting’.  Is there a team member who’s the ‘smartest person in the room’ and everyone else has to put up with it?

Project savior.  I can’t tell you how many times I’ve been asked to look at a project started by other developers and the project owner is desperate for it to get done.  In these cases they’ve spent a LOT of money with a developer and gotten poor, or no, results.  You have to ask yourself a few questions.  Was it the developer being incompetent, the owner being unreasonable, or both?  If you take one of these projects you can either be the hero by completing the project, or you can be the goat for being just as incompetent as the original developer.

Project owner/developers.  I’ve found that working with project owners who are also part-time developers also can be a pain to work with, but not always.  The ones that come to me realizing that creating an application isn’t easy and requires time they don’t have and knowledge they don’t have time to acquire tend to be okay.  Those that say it should be ‘fast’ and ‘easy’ for someone with your skills have their expectations set too high.  Software development, in many respects, is more art than science.

Always complains about cost.  Every client wants their custom software done cheap, quick, and on time.  The industry joke is to pick two of those qualities.  Software development of custom software isn’t cheap, nor is it quick in most cases.  If they balk at the initial estimate it probably won’t get any better.  They certainly won’t like any change orders.  We had one prospective client ask us three times, over the course of a year and a half, what the price was going to be to complete their project.  I don’t know if they expected our price to go down, or what, but eventually they found a developer to do their project at the price they wanted.  And then had the audacity to come back six months later then that developer couldn’t deliver.

Been through many developers.  Perhaps my biggest red flag of them all is when someone comes to us after going through several other developers.  Listen to their complaints about the other developers.  Were they too slow, did they charge too much?  I’ve even asked for permission to contact the previous developer to get the news from the developer perspective.  The community is small so there’s a good chance I know them and I know I’ll get the developers perspective.  Use those connections if you can because you might discover some useful information about the client and the project.

Just because you need the work doesn’t mean you should take every project that comes your way.  Be selective because you’ll avoid some heartache and probably enjoy your work more.  What red flags have you developed over the years?

A Short Video is Worth a Hundred Emails

One of the ‘joys’ of consulting is the language difference between developers and the customer.  Developers have a ‘language’ and clients have a completely different ‘language’.  A perfect example is when a customer says ‘the application crashed’ and trying to interpret that.  I usually end of asking, did this crash mean a dialog appeared saying something happened (an exception was caught), or that the app just went ‘poof’ and disappeared (something way more serious).  For Xojo developers those two definitions of ‘crash’ mean totally different things.  Those nuances mean nothing to the customer.

Email is a notoriously bad way to communicate.  It’s easy miss details, or worse yet, misconstrue intention.  It’s easy to read anger, annoyance, or <insert feeling here>, that the sender did not imply.

We’ve had instances where we go round and round with a client via email on some detail when a simple phone call would have solved the issue within five minutes.  I know it’s not ‘modern’ but sometimes a simple phone call solves a lot of issues.

More recently I’ve had a client say that a sequence was wrong and described it with some detail.  I took a stab at the fix and then gave them another build for testing.  Still had issues.  The problem was that they’re not describing what’s really happening – they’re using customer language when I needed developer language.  The solution was a simple video.

Most people have a smart phone that can take video.  In my case, once I knew what the customer was really doing it was a simple fix because I could see what they were really doing.

Voice calls are important, videos are important, and doing screen sharing is becoming another important factor.  Think about using any of these tools before sending yet another email.

You Don’t Need to Be A Rock Star

I have been a Xojo consultant for nearly fourteen years.  It’s crazy to think it’s been that long and it’s sometimes hard to remember back to the early days of how I knew nothing and didn’t even realize that I knew nothing.

It also tickles me to no end that people consider me an ‘important’ person in the community.  Some might even consider me a ‘rock star’.  I claim no fame in the Xojo world other than I’ve stuck it out when many other developers have left the Xojo ecosystem.  Let’s just say that at times I feel like I’m the Last Man (consultant) Standing.

Can you become a Xojo consultant?  Absolutely!  There is nothing special about what I’ve done and you can do it too.  I have an electrical engineering degree so it’s not like I’m an idiot and it wasn’t until I met my wife who happened to be a software developer that I was given permission to change careers.

In retrospect that was the best thing that ever happened to me (besides meeting the love of my life).  I was an uninspiring engineer and I dreaded many of the tasks that I performed on a daily basis.  Software development, on the other hand, inspires me.  I wake up every day and (usually) can’ wait to start coding.  The fact that I get paid to do it is just icing on the cake.  To get paid to do what I love?  Sign me up!

If you know a little bit about Xojo you can become a consultant.  First, ask yourself WHY you want to be a consultant.  If it’s for the money don’t expect it to happen right away.  I think it was two or three years before we really made any money at it.  It took six years before I hired a second developer and ten years before a third and twelve before bringing my wife on as a software developer (she had always been doing those pesky taxes and payroll things that I hate doing).

So if you do become a consultant don’t expect to make money right away.  Or if you do, don’t expect the money to be consistent for a number of years.  Even now we fight with cash flow so it takes some discipline to ride out the really good times when cash flow is great and the not-so-good times when cash flow is poor.

The road to becoming a ‘name’ is not a quick one.  I spent many years in obscurity.  The first developer conference I went to I was a wall flower and barely talked to anyone.  By the third conference I co-hosted a session with another consultant because I didn’t feel like I was qualified enough to do it on my own.  Now I’m a regular presenter at the developer conferences.

One way to become a recognized name in the community is to teach others.  I’ve written a fair number of tutorials and example projects and I decided to doing video training and so far I’ve got about sixty-two hours of video available for streaming (and offline use now) with hundreds of individual videos and project files for new developers to learn from.

I think this is the part that makes people think that I’m a ‘rock star’.  I get people coming up to me all the time at conferences and engaging me in conversation and thanking me for some forum post, tutorial, or training video that made a difference for them.  It’s gratifying and sometimes a little scary (as an introvert) to have people do that.

Here’s my dirty little secret on those tutorials, example projects, and training videos.  Those are my way to learn something about Xojo and leveraging that experience for others.  Put another way:  The best way to learn something is to teach it to others.  If you are not doing something like this (maybe not for sale but for yourself) you should be.  That’s the only way you’re going to learn parts of Xojo you don’t know as well.  You really don’t want to learn new stuff on client projects (though it does happen occasionally).

As a consultant I don’t know everything.  There are still things that I’ve never touched in Xojo and things that I touch so rarely that I have to go relearn it.  Those small projects become invaluable review later on.

I don’t want to discourage anyone from becoming a Xojo consultant.  It’s not an easy road at times and it is sometimes frustrating and you put in long hours and you deal with bad clients and all the really bad things that come with consulting.  But the money can be good, it can be fun, it can be rewarding, and some clients you’ll be friends with for many years.  If you love, truly love, coding and enjoy the mysteries of it and putting the pieces of the puzzle together then maybe you, too, can become a rock star consultant.

Happy coding!

The State of the Xojo 3rd Party Developer Market [u]

BKeeney Software offers a variety of Xojo developer tools for sale. BKeeney Shorts is a reporting tool unlike anything else in the Xojo kingdom and allows you complete control over your reports. That is its strength and also its weakness since you have to fully code your report. We also offer a Calendar class for use in desktop applications, a cross platform Spell Checker plugin, and ARGen that creates the classes that ActiveRecord uses to make database coding easier and quicker in Xojo.

Over the years we were approached by developers that were leaving the Xojo market and wanted a home for their product. When True North Software decided to exit the Xojo market we purchased the rights to Formatted Text Control, RB Code Reports and a number of other Xojo related tools. When Pandaware left we picked up Simple Help Editor and Styled HTML Field. Many people were asking for PDF classes and had fond memories of Fireye Software’s PDF classes so we tracked down Asher and acquired those too.

We purchased these products from their respective owners either because we already owned the products or had a use for them. In some cases we simply updated the source code and in some cases we started a complete rewrite to suit our needs. This means that in addition to the original thousands of man-hours the original developers used to create them we’ve invested significant time and effort ourselves to work on them.

BKeeney Software can’t exist on the sales of these developer products. Developer product sales are lucky if they top 20% of our annual income. Most years it’s less than that. Our second highest income earner is our Xojo Training material but, by far, our best income source is our consulting services. With multiple Xojo developers that makes sense. Not only can we throw all of our developers on a project we can (and usually do) all work on separate projects. When one of us is idle (which thankfully isn’t very often) we find time to work on our applications and developer products (and me on training material).

I was on the receiving end of a grievance on the forums this week where I was accused of not delivering updates that I promised on one of the products. If I did nothing but work on our products I’d be out of business in short order and that product would just go away and who knows if anyone would pick them up.

This got me thinking. Am I unique in this position? So I queried some other Xojo developers to find out what the state of the Xojo 3rd party market is like and if they would share their thoughts. I received more information back than I expected.

Almost all of the developers I contacted said that product sales were a minor portion of their income with most stating it was less than 20% of their income. Jérémie Leroy has a full-time job and the Xojo business is just a happy sideline. Sam Rowlands said there was no way the sales of his developer products comes close to paying for itself. And,one of the more well known figures in the Xojo community, Christian Schmitz said, “Even with the scale I have with MBS myself. Consulting keeps the company running.”

From these statements, it’s pretty obvious that the 3rd party market, while not exactly stagnant, isn’t thriving either. Everyone I talked to has other sources of income besides their developer tool/utility sales. Part of this is probably because the Xojo market is small. Another reason might be the hobbyists that Xojo attracts and they simply don’t have the means to purchase tools. Another possibility is that Xojo has ‘good enough’ tools built-in and newcomers don’t need the more advanced commercial, add-ons.

One of the interesting comments I received from several developers was that it was those that purchased the cheapest version of their products (some offer encrypted and non-encrypted versions) created the most work for them. I’ve seen this myself with our encrypted source code that it seems to generate more support tickets than the full-source versions. Based on this feedback I am seriously considering removing the encrypted versions from our store and simply selling the full-source versions. It’s interesting that our one product that doesn’t have encryption (Formatted Text Control) doesn’t generate that much support help despite it being one of the largest and most complicated products we sell.

All of the developers I contacted felt that the future of Xojo is bright and holds promise. iOS development in Xojo might become as big as desktop and web which means new customers for their products. The new framework causes concern for many in the Xojo community but the developers I talked to were ecstatic that Xojo was listening to our concerns and making incremental changes to the new framework based on that feedback.

The 3rd party Xojo development tool market is tough business to make a living at. The fact that half our products came from developers leaving the community says something. That some of the most well known and respected voices in the community can’t make a living selling Xojo developer tools and have other sources of income is also telling.

So what can Xojo do to help us out? Growing the user base is the biggest thing they can do and it seems that having the iOS version is a step in growing the platform. One area of concern, though, is that many Windows users are unhappy with Xojo right now. They feel, rightly or wrongly is besides the point, that the focus has been so Apple and iOS oriented the past couple of years that they feel unwelcome. Some focus on making the Windows experience better would be reassuring to them.

I also think that Xojo could do more to promote the 3rd party products. Perhaps the Xojo Developer Evangelist could pick a product to review each month. Xojo Developer Magazine does reviews like this but it doesn’t receive the eyeballs that the official Xojo site gets. Personally I’d offer a discount for the people that purchase via the review. The market isn’t THAT big and it would be a good way to show off some products and generate sales for developers that are starving for income. More income means more of time for product development and everyone wins when that happens.

I feel the future is good. More Xojo users means more product sales (hopefully). This, in turn, means we can spend more time on those products and pump out updates on a regular basis. Until then, us 3rd party Xojo developers will continue with our labors of love and put updates out when we can.

What do you think of the 3rd party market? What could Xojo do to improve it?

[Update:  ]

After looking at our 2014 numbers our total developer products and training sales was LESS THAN 10% of our total income.  In 2013 the amount was more but amounted to less than 5% of our annual income (consulting was VERY good that year).  In other words, if we relied on our developer products and training to make a living we would quickly go out of business.

Seriously, why do I even bother with developer sales?  Just using them and updating them for ourselves would be cheaper in the long run.

Client Red Flags

I’ve talked before about those little things that prospective clients (and sometimes actual clients) do that should give you cause for concern.  These are those things that should be red flags and make you reconsider taking them as a client, or not keeping them as a client.  We recently took on a new client that had already burned through another Xojo developer before coming to us.

I’ll start off by saying that we have an entire stable of clients that came to us after they had tried out another developer.  Roughly 75% of our long term clients have come to us this way.  For some, the developer left the industry and recommend us to their client but for some the Xojo consultants had failed to deliver a working application even after quite a bit of time and money.  The clients came to us and they’re happy that we have multiple developers and have a breadth of experience that is hard to find elsewhere.  We’re also not going away anytime soon.

This client should have raised enough red flags for us to avoid from the start.  But, honestly, that’s easy to say in retrospect.  Sometimes you just won’t know until you work with them for weeks and sometimes months.  Plus, it was a smallish project that was only a couple of weeks long.  What could go wrong, right?

The clients first developer underbid us by a grand total of 10 hours but had significantly lower billing rate.  A couple of months later the client parted ways due to lack of progress from the first developer and called us back.  Red flag number one, in my opinion.  Clients have every right to be price conscious but one warning sign is if they’re trying to get the project done ‘cheap’ and ‘quick’.  While possible they also need to be flexible and this client was anything but.

The second issue with the client is that they kept using phrases “we want it exactly like this,” with ‘this’ being a VB6 application that looked like they coded it in 1995 and an HTML website that harkened back to the 90’s as well.  Even if Xojo could create such an application (it can’t without significant work) I’m not sure I would simply because creating a 20 year old GUI isn’t something I strive for.  We were going to create modern GUI (nothing crazy – just want Xojo gives us) with a database backend so the application could scale.  But they demanded flat files and a UI that looked ‘exactly’ like their prototype (which was non-functional).  Their reasoning?  Because they understood it and ‘their generation’ understands that look.  Hm…okay.

I guess my biggest issue with this client is they chose Xojo – not us.  There was nothing in the project spec (a VB6 app, a simple HTML web site, and some phone meetings) that said it couldn’t be done in Xojo and when we heard ‘just like this’ we translated this to mean ‘as close to this in Xojo as possible’ and when we didn’t make it look like the 90’s website they were mad and cancelled the contract despite us redesigning the app twice in attempt to mollify them.

In retrospect, the client doesn’t really want a Xojo developer.  They want an HTML and php developer that will do exactly what they want.  No more.  No less.  The signs were there from the beginning – we just failed to see it.

In the long run it’s just another red flag example that I hope to learn from and I hope that you don’t have to go through either.

You Have a Contract, Right?

Writing software for others can be a tricky profession.  The client often has totally unrealistic expectations on how software development works.  They give vague requirements (or none!) and expect you, the developer, to read their mind and produce an awesome application.  And therein lies the problem, because there’s a wide difference between their requirements (or lack thereof) and the finished project.  A handshake and a verbal agreement just isn’t good enough – You need to protect yourself (and the client) with a contract and spell everything out.

If you don’t have a contract already, my preferred place to begin is by going to Docracy (www.docracy.com) and looking up contracts.  These forms aren’t perfect, but they’ve been looked at by lawyers, and in-lieu of hiring your own lawyer, a heck of a lot cheaper.

The basic contract has little over a dozen sections.  I’ll just highlight a few of the sections that seem to grab peoples attention.

A payments section is obvious.  It gets into the details of how you’re getting paid.  More detail is good.  What’s the rate?  How long is it good for?  Is it a fixed bid?  What is the payment structure?  Do you have a separate rate for bug fixes and for how long?  When can you revisit rates?  Do you take check or credit card?  Do you have a fee for taking credit cards?

The expenses section should detail everything that you are paying for out of your own pocket (like computers, development software, etc.) and what you expect the client to reimburse you for.  This could include travel expenses, special services, software, or plugins required for the project, postage and courier services or any number of legitimate things.  The point is that you need to document it!

One section that has caused me some issues over the years was the intellectual property ownership section.  Every client wants to own the code you’ve written and this section gives any patents or trade secrets developed for the project to the client.  I have, as many consultants do, a stable of controls and classes that I reuse on nearly every project which really can’t be the clients’ property when the project is done.  This is where the consultant’s materials section comes into play.

Consultant’s materials are the tools, or pieces of code, that were in existence before the work began that you use to get the job done.  You can give the client nonexclusive rights to the software with some exceptions (spelled out of course), or you can attempt to retain the rights to your own software.  Regardless, this section should be read carefully so that you and the client thoroughly understand the implications.  It has been my experience that this section almost always needs an edit or two to satisfy everyone.

A lot of clients also require a confidentiality agreement section that says that you won’t talk about your work for the client to others without permission from the client.  Sometimes they also want a non-compete section stating that you won’t work on similar software for a certain number of years.  Make sure that you understand the implications of these sections because it might mean you lock yourself out of an industry!

All of the above is fairly generic and is applicable to nearly all contracts.  In my format, the exhibit document is where a bulk of the details occur.  Here is where I list my deliverables, the client deliverables (I don’t like doing graphics so I usually require that the client do them), a listing of any requirements that I’ve received so far (referencing emails and other documents if need be), assumptions that went into the bid, payment schedule and amounts and milestone dates.  As you can image, the exhibit may be much larger than the rest of the contract.

In the client deliverables section, I always state that the client is responsible for final application testing and that they are responsible for end-user support.  The reason that clause is in there is that a client assumed I was doing all the testing and was going to perform end-user support.  This is why writing everything down is so important!

One of the assumptions I generally add into my Xojo projects is that Xojo can actually do what I, and the client, assume it can do.  I only had one issue ever come up and because of that assumption we were able to negotiate a slightly higher contract price to purchase a pricey third-party control.

In the exhibit I add a section that describes how long after the final sign-off I’ll fix bugs for free.  I also state the rate for the following year on program changes (new functionality, not bugs) and when I can renegotiate pricing.  This section can be contentious.  I’ll fix true bugs for a long time, but a lot of times the client doesn’t understand what a bug really is and how it’s different from their poor (or nonexistent) requirements.  If you find a problem client, this will probably be one of the areas that causes you grief.

There’s a lot of information that will be in your contract.  It’s designed to protect you and your client against poor assumptions.  It provides a way for you to handle the client and set their expectations upfront.  In the long run, a good contract will be the roadmap of your projects.

Why have a contract?  Because not having one may cost you  a lot of money.  I turned down a project a few years ago because the prospective client balked at having to pay money up front.  In indignation he claimed in 30 years he’d never paid anyone up front.

He then proceeded to go through the rounds of contractors and they all turned him down for much the same reason.  Finally, he found a developer that was looking for some extra money but already had a full time job.  He did the work (without a contract and without any up front payment).  And, as you can imagine, the client shafted him in the end.  Said that it didn’t work as promised so therefore wasn’t going to pay.  The client was full of it because he walked away with the source and never looked back.

The developer lost thousands of dollars and had no way to enforce it since he didn’t have a contract in place.  Even having a contract won’t stop a client from not paying but at least with a contract the developer could have gone to small claims court to recover some of the money.  No contract meant no such recourse was available.

I think we all have contract horror stories.  Have any that you’d like to share?

Names Mean Something

This week I had an ARGen user contact me.  They had purchased a license and it wasn’t outputting the tables like it should.  He was able to send me the database and I confirmed the problem.   I looked at the XML file that ARGen was producing and it appeared to be an error in the XML generation.  I did a quick fix and sent it back to him.

Except, that didn’t really solve the issue.  Silly me for not looking more into the issue (it’s good to be busy, but sometimes…).  Of his four tables, only the first two were generated for the DataFile namespace we use for ActiveRecord.  Digging into it some more I discovered that Database.FieldSchema was failing.

Silly me for not checking for a database error.  I find this ironic that I preach db error checking and I didn’t check it in that particular case.  I guess I just didn’t think that FieldSchema would return an error.  Anyway, the SQLite database had a table named ‘group’.  That happens to be a reserved keyword in SQLite and you really shouldn’t be able to do it, but some tools will let you do it anyway.  In fact, all of my tools let me do it but they must be qualifying table names internally.

In SQLite, if you put single quotes around the name like ‘group’ it will work.  In a quick test against MySQL and PostgreSQL that doesn’t work and generates a db error.  Now ARGen checks for the error and will warn if it bails prematurely because it can’t find the schema of a table.

I also recommended to the developer that he change his table name.  Having ‘group’ in every SQL statement is going to be a royal pain.  It’s easy to forget and unless your QA and testing staff (stop laughing and catch your breath) tests every single code path it’s quite possible that your customer will find it before you.  Why make life harder on yourself?

Which leads me to what BKeeney Software does.  Carol, our resident DBA (otherwise known as the Database Goddess) has a bunch of naming conventions for databases.  All tables have a prefix.  Regular tables have a “t_” prefix.  Reference tables like states, types, zip codes, etc, get a ‘tr_’ prefix.  Tables that are a many to many relationship have a ‘tx_’ prefix.  Views get a ‘vw_’ prefix and stored procedures have a ‘sp_’ prefix.

Some other rules:

  • Table names are never plural.  It’s never t_people, it would be t_person.  t_check not t_checks and so on.
  • If it’s a child table it will have the parent table name in its name.  So an invoice line items table might be t_invoicelineitems.
  • Avoid abbreviations unless it makes sense to use them.  We just finished a large accounting app with payroll.  We had well over 100 tables JUST for payroll, so rather than having payroll spelled out in every single table we just used ‘pr’ in the table names.
  • For the Primary Key field we insist on auto increment integers.
  • Primary key field name cannot be a simple ‘id’.  It’s too easy to get confused with which ‘id’ you’re talking about in joins.   Our primary field name is TableName_ID (underscore ID at the end).  So the primary key for t_person would end up being Person_ID.

I’m sure some of you are thinking that these rules are overboard and I’d agree if I didn’t do a dozen large database applications every year.  Once you get past a dozen tables or so things start to get confusing so having rules give us some advantages on big projects.  At a glance we can tell the function of a table.  Time is money and with a staff of four, the last thing we want to do is make it harder for a team member to determine what the function of a table is.

Names mean something and some names have implications.  If the developer had used our naming rule so that his table name was t_group, ARGen would have had zero issues.  Oh well, it was an instructive bug report.  I get to chastise myself for not doing some error checking and I get to write about it.

What things do you do on databases to make your life easier?

Differentiating Your Services

There are hundreds of consultants out there doing the exact same thing you do.  They’re hustling to sell their services to the very same people you’re trying to sell to.  They don’t live in New York city or San Francisco and can live on $15/hour.  How can you, a good developer, compete with overseas programmers or newbies?

Let’s be honest.  If the client is evaluating potential developers solely on price then you probably don’t want them as a client anyway.  That’s not to say that price should be ignored because a client that’s not frugal with their money is a problem too.  But, it is possible to win a bid even with a higher end price.

So how do you differentiate yourself from the cheap programmers?  The first thing to have is a page on your website that shows previous projects.  This shows potential clients the type of work you’ve done before.  You have to be careful about violating any Non-Disclosure Agreements you have, but for the most part you don’t have to get into specific details about a project to portray the type of work it was.

If you’re just starting out, your previous projects page is going to be sparse.  Another drawback is when your previous projects page doesn’t show the skills the client is looking for.  Unfortunately, the only way to get around this problem is to be upfront with the client and let them know you’ve done the research and have a plan.

Do you have off-site storage of source code?  If you’re working out of your house (who needs an office anyway?) you should probably have automatic backup of source code to an off-site facility.  In the event of a disaster like a flood, fire, earthquake or someone breaks into your house, this is a simple and inexpensive way to protect your work.

We use a Subversion host that gives us gigabytes of storage that amounts to hundreds of Xojo projects files along with documentation and other supplementary info.  The host itself has offsite backup storage and hourly backups.  Does this sound paranoid?  You bet it does!  Your code is your money maker and the client isn’t going to be willing to fund several more months worth of work because your hard drive crashed or your laptop was stolen and you have to recreate your work.  They don’t care, they just want the project done.

Bug tracking systems like Bugzilla, Mantis and many others are good open source software applications that make bug tracking cheap and easy.  Using a bug tracking system is light years ahead of working strictly through email, if for nothing more than the documentation features and audit trail features.  The client can log into the system and see a bug’s status and add additional information.  You, as the developer, can request additional information, close a bug, or merge it with another one.  A good bug tracking system is a must on large projects or projects with multiple developers.

Oddly enough, the other thing that can differentiate yourself from other developers is your contract (you do have a contract, right?).  A good contract is not only protection for you and your client legally, it is also a way to document what you will and won’t do.  It’s the first step into managing the expectations of the client.

Contracts can be a pain to create.  Start with a standard contract.  I’ve been pretty impressed with the documents at www.docracy.com.  Once you have one you like you can add to it.  We use a standard boilerplate contract that is fill-in-the-blank for the basics (name, address, etc) and has general responsibilities for us and the client.  We constantly refer to Appendix A that lists all of our deliverables (source code, installers, documentation, etc), client deliverables (graphics, timely testing, etc), a brief description of what the code will do, and the payment terms.

Price is important and you’ll lose some clients because of it.  It happens.  But using some of the tools and techniques we’ve talked about you can differentiate yourself from the cheap and inexperienced developers.

What things help differentiate you from other developers?