How to explain to non-programmer to build my Visual Studio source code in "Release" mode?

Question

I'm writing documentation for some software that I wrote. Specifically, I'm writing a guide to installing the software. I'm delivering the source-code to my client, so I expect that they will want to be able to build from source.

I explain to open the solution in Visual Studio 2010 and to right-click on the project and select "Publish".

There doesn't seem to be a clear and straight-forward way to explain that they must build it in "Release" mode or what the simplest way to explain how to do that is.

What's the best way to explain this?

Edit: In response to the comments asking me to be more specific, on my setup of Visual Studio 2010, there is a drop-down list next to the green icon that starts the debugger. It doesn't have any label next to it. That's how I'm familiar with changing the setting myself, but I don't want to write in my documentation, "Click on the drop-down list next to the green button and select "Release". There's got to be a better way. I am particularly concerned that if I get in wrong, it could result in someone changing the setting at the project level instead of the solution level.

Answer 1

I would just add a command line script (*.bat) to your package, calling VS with commands like

set VSPATH=C:\Program Files (x86)\Microsoft Visual Studio 10.0
set DEVENV="%VSPATH%\Common7\IDE\devenv.exe"
%DEVENV% YourProgramsSolutionFile.sln /build "Release" /out Build.log

This script can be run by a simple double-click, which should not be too hard to explain to anyone else, programmer or not.

Actually, I find it very cumbersome to force a non-programmer to install Visual Studio on his machine only to let him compile your program. So when you want to deliver a package to someone else, why don't you provide a setup routine for an already compiled binary additionally to the source code?

Here is a related article you might find interesting: http://www.codinghorror.com/blog/2007/10/the-f5-key-is-not-a-build-process.html

Answer 2

I would add a note "build in Release mode" to the doc and assume the reader (either the client or a developer hired by the contractor) is competent enough to find the right button to push.

There is a minimum skill level required to make even trivial code changes and I'd include this as one of them. Put another way, if your reader needs instructions on how to build in Release mode, what are the chances that they're qualified to not break the code through ignorance?

It makes perfect sense for the client to request the source code - they paid for it. If they don't have the skills to make changes themselves, they can hire it out to someone else.

FWIW, I count myself in this category. In some environments I can certainly build code. In others I know better than to do anything more than look over someone's shoulder.

Answer 3

Since this is for a non-technical client, I would ask: Why are you even requiring them to build from source?

Instead, if the want the source code, do the following:

1. Build a release of your software for them and deliver the executable binaries
2. Also deliver the source code to them

This is really the best mechanism for them to receive your software. If they need to run it on multiple platforms, that's all the more reason for them not to have to compile your source. Instead, deliver prebuilt binaries for all their target platforms.

You can still deliver the source code while offering a much better initial user experience of delivering prebuilt binaries. That's much preferable to going through any documentation on building it themselves, no matter how well the documentation is written.