Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

As an independent vendor being contracted to write a product for a company, is it reasonable to ship only the source code and user documentation while leaving out design documents, architecture diagrams, unit tests etc (basically anything else not strictly needed to run the product or extend it)?

The goal is to make the end product extensible for the client so they can further its development internally, but not for free. They would have dig deeply into source to make sense of some design decisions etc, and they'll be responsible for writing their own comprehensive tests to guard against regressions being introduced.

The idea here is not to make the code unintelligible. I would just like to create future opportunity for being contracted to write extensions by virtue of the "inside knowledge" and expertise I have from being the original author.

Would this be considered unethical?

Edit: The contract is currently being negotiated, so the issue of what constitutes final deliverables hasn't been firmly decided. Additionally, I should have mentioned I will maintain ownership of the product. I will only grant to the client a usage license. Does this detail make a difference in whether this is regarded as bad form?

share|improve this question
4  
What does the contract say you need to do? –  user1249 Jul 29 '11 at 10:05
    
The contract is currently being negotiated, so nothing has been firmly decided. –  Bernie Jul 29 '11 at 16:37
1  
If so, then consider letting the price reflect what they want you to ship. –  user1249 Jul 29 '11 at 16:43
1  
Obvious advice: make the contract very clear so there is no ambiguity on what will be the duties! –  Agos Jul 29 '11 at 21:00

9 Answers 9

up vote 24 down vote accepted

Contractually they'd be smart to include some sort of clause about the scope of the documentation they want. They should compensate you for presenting them in an understandable and professional format (redo the napkin sketch).

It's not unethical to only do what is asked and paid for, but to go out of your way to withhold information is just wrong.

If you give me a poorly documented and convoluted app that I can't work with, I'm more inclined to think you're a bad programmer than some sort of genious my company can't do without. Build a reputation for doing things right.

share|improve this answer
    
I don't think that he was going to give only half the documentation, just only what matters: All of the end user documentation he has. I would call leaving out architecture and design charts "crippled" documentation –  TheLQ Jul 29 '11 at 9:58
1  
Building a reputation for doing things right is just table stakes. Why not build a reputation for going above and beyond? –  Scott Wilson Jul 30 '11 at 2:01

I would consider that unethical, yes.

share|improve this answer

You're only hurting yourself. If their internal staff looks at what you've done and finds a complete lack of documentation, they're going to think you're a goofball and will be less likely to retain you in the future.

share|improve this answer
    
+1 I agree. Sometimes giving something away today, pays off for you tomorrow. Obviously you need to keep that in perspective. –  user29981 Jul 30 '11 at 1:38
    
That's true, but I wouldn't even call this case truly giving something away. This should be considered part of the whole package they paid for. BTW, super easy way to tell if something is unethical: how would you feel if you were on the receiving end? –  Scott Wilson Jul 30 '11 at 2:00

Did you charge them for developing the unit tests and documents? and did they pay the invoice? If so, then they are entitled to receive what they paid you for.

Otherwise next week we'll see a question here on p.se.com titled 'How do we force our contractor to give us all the technical documentation and unit tests we paid them for?"

share|improve this answer
1  
Bernie mentioned that the deliverables haven't been negotiated yet. When you pay for a product, you don't necessarily pay for all source code, architecture diagrams, research, IP, etc. You pay to receive the deliverables. –  Kristofer Hoch Jul 29 '11 at 17:09
1  
read his edit, the project hasn't even been agreed upon yet so it will all depend on how the customer negotiates. Generally if the SOW and the invoice include an item the customer will want it. The customer may use non-delivery as an excuse to refuse payment or only partially pay, no matter what the rest of the contract says. –  james Jul 30 '11 at 1:45

I'd assume at this point there would be a contract or written agreement/document in place listing all documentation that you have to deliver to them.

If not, you could make it clear to them that customization of the product - beyond that in the user guides - will require additional knowledge of internal code workings. And if you're in a negotiating position, you could ask them to contact you for further enhancements and get paid for it.

From what I understand, you're already getting paid to write the code for their product, i.e. they own it. So they can consider it unethical if you leave without documenting it all.

I'll suggest you do write a skeleton outline document with a High-Level architecture and pointers on where to look for the key feature enhancements. Which are the key files and so on. If your work is good, they will be happy to come back to you for further tasks.

share|improve this answer

There are really two questions that need to be answered here, and I'll address them both:

  • Do I have to provide that documentation to the client?
  • Should I provide that documentation to the client?

Do I have to provide that documentation to the client?

You have to provide them what your contract says you'll provide them. In my opinion, that means that if the source code can't be reasonably maintained/modified without also supplying the documentation, then you also need to provide the appropriate documentation.

You may want to look at Works Made for Hire Under the 1976 Copyright Act by the US Copyright Office to see if the documentation, unit tests, etc. are actually owned by your client. If they are, you definitely want to provide those to them.

Should I provide that documentation to the client?

If you ever want to do business with them again, or if you want them to recommend you to other, then you need to do whatever work is necessary to turn them into raving fans of your business.

That means that you need to turn over to them the highest quality source code, adequately commented, and anything else that they would be interested in having. My advice would be that when you meet with them to hand over the deliverables, be prepared to give them the unit tests, etc. After you've gone over all of the big important things, then say something like, "By the way, I also generated unit tests for these components. Do you want those, too?"

Work to generate loyalty with your customers, and you'll get their business again in the future.

share|improve this answer

If you billed those hours then they own it. You should turn over all work product. The exception would be anything you did, but did not bill for or purchased and did not pass along the costs for. (i.e. your computer, development software etc.).

share|improve this answer
    
Hmm... Only if that's what the contract says. –  Sean McMillan Jul 29 '11 at 20:25

I would ask which of these you think describes you:

You're being paid for your expertise in designing and making software, establishing what the business problem is, and managing the project as a whole. You charge them a license fee, they don't own the software or the design, and you hand them the source code just to make them feel better - they really have no right to use it.

or

You're being paid for your time to design and make software for them. They know the business problem and they're managing the project. They own the design, the software, the source code, and all the work products you create during hours you bill them for. They have full rights to use all of that however they want.

Don't try to mix and match those two setups. You might charge more for the first (since you're bringing more skills to it, and taking more risk) or less (since they end up owning less) or the same (if you think those things balance out.) We generally do the first one, and we get rehired time and again by being great, not by with-holding information. If you've been living life the second way and want to move to the first way, there's a lot more to it than not sharing your design documents.

share|improve this answer
    
+1 for "we get rehired time and again by being great, not by with-holding information." It's worked for me, too, for many years. –  Bob Murphy Jul 30 '11 at 1:31

I like this article: http://unixwiz.net/techtips/be-consultant.html

What you are describing would not give me the Warm Fuzzy Feeling about ever working with you again.

You might be a genius, but if you fall over dead from A Bus, I need to maintain what I bought from you.

If you don't give me that ability, I am never going to again hire you or recommend hiring you for anything I deal with.

Now, if you are selling a binary, e.g., a "custom shrinkwrap" where you can sell the same product to other companies, then it's more reasonable to work off the "less information" model, because now you're selling a product.

The difference is that with source, I am purchasing the ability to modify the source code down the road. However, with binary, I am simply purchasing the ability to run it.

share|improve this answer
    
+1: Based on the "bus factor", I send unsolicited design docs, etc. on my clients, and actively push them to replicate my builds occasionally themselves. "Taking the high road" has worked so well, I'm turning away new work right now. It's also been my experience that trying to squeeze someone's metaphorical gonads does not usually generate a trusting relationship leading to repeat business. –  Bob Murphy Jul 30 '11 at 2:01

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.