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.

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.

share|improve this question
5  
I'd record a screencast video. –  user16764 Oct 11 '13 at 20:50
    
Sharing your research helps everyone. Tell us what you've tried and why it didn’t meet your needs. This demonstrates that you’ve taken the time to try to help yourself, it saves us from reiterating obvious answers, and most of all it helps you get a more specific and relevant answer. Also see How to Ask –  gnat Oct 11 '13 at 20:52
    
could you explain to me why it is necessary? what if they fat mouse it and build it in some other mode? what exactly is going to happen? –  Andyz Smith Oct 11 '13 at 20:55
    
isn't there a whole project setup dialog that has these settings? you could give some instructions for that. the one next to Green Go Button is really a shortcut for people familiar. but Doc's answer is really much better anyway. –  Andyz Smith Oct 11 '13 at 21:43

3 Answers 3

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

share|improve this answer
2  
prebuild binaries are great, even better if you add an installer that will do most of the cumbersome setup or simplify it with a GUI –  ratchet freak Oct 12 '13 at 0:39

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.

share|improve this answer

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.

share|improve this answer

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.