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.

I found myself in a pickle after writing some specs for freelance programmers that I hire.

It seems that I'm missing some basic structure and I'm not placing the points in clear enough view for the programmer to understand.

Any advice that would help me convey the specs better to an average Java developer would be very helpful.

For example:

I have spring project that is very complex at this point. And I'm hiring people to integrated all sorts of payment, social and authentication APIs. (it is the site in my profile if you want to have visual example)

As far as they are concerned they will be working only with small segment of the project so no need for the big picture.

I require first sample application that will perform what I need outside of the spring container. Than I have the developer integrate the logic into existing system.

In specs I usually traverse the input from UI to the the database, with little examples here and there. What I found is helpful to just make draft of the specs and have the developer put his input in it and then adjust the specs after.


migration rejected from stackoverflow.com Oct 23 '13 at 12:13

This question came from our site for professional and enthusiast programmers. Votes, comments, and answers are locked due to the question being closed here, but it may be eligible for editing and reopening on the site where it originated.

closed as too broad by gnat, MichaelT, GlenH7, Yannis Oct 23 '13 at 12:13

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs. If this question can be reworded to fit the rules in the help center, please edit the question.

Care to share an example? –  diagonalbatman Mar 22 '11 at 15:23
There is an article series from Joel Spolsky about this topic. –  Paŭlo Ebermann Mar 22 '11 at 15:29
I don't think there is anything special about specs for "Java programmers" than any developers using any other language. –  matt b Mar 22 '11 at 15:32
I agree but I'm Javist (if there is such a word) so I like to relate everything to Java. –  Mat Banik Mar 22 '11 at 17:53

4 Answers 4

Who is doing the design?

If you are outsourcing the design as well as the programming, then provide them with use cases. They will construct a design to minimally cover the use cases.

If you are outsourcing the programming, then present them with a set of design documentation. There are many design templates out there, but if you need a head-start you might want to try ready-set.


Give them use cases which demonstrate end-to-end functionality.

could we call that a user story ;) –  Tim Williscroft Mar 23 '11 at 1:19

I work as freelance programmer. Apart from big picture, architectural details and wire-frames.. there needs things to be communicated very well. Skype is real help. Very often, you will find yourself repeating the same thing, but believe me, it helps your program to get complete grasp.

I come to believe that once you and your freelance team understand each-other's style, thing are as smooth as your own team. So,

  1. Explain the big picture.
  2. Use wire-frame. Live example or similar products.
  3. Bird view code architecture.
  4. Communicate and stay available whenever you can. Skype is the best tool for this.
  5. Do not hesitate in repeating things that you have explained already. Sometimes, things don't become obvious the first time.

All the best.


As far as they are concerned they will be working only with small segment of the project so no need for the big picture.

I'm not sure that's a good perspective to have. In theory, individual programmers don't need to know the big picture. However, in order for the project to succeed, you (the designer) need to unambiguously specify every component of the program. In addition, every developer needs to implement that specification perfectly. It can work, but the chances of something going wrong are much greater than the chances of everything going right.

Allowing your programmers to see some of the big picture allows them to help you by finding potential pitfalls or ambiguities in the design. It also allows them to evaluate when an implementation is not up to specification and alert you appropriately. Without that perspective, developers have no option but to do the best with what they're given - resulting in an application with lots of ugly hacks and workarounds for poorly defined APIs. At least, that's been my experience.

The project is design to have modules put into in form of plugins. The system never depends on the feature that is being integrated the feature just brings additional functionality. I think it is called modular design and lot of programmers I worked with like it. –  Mat Banik Mar 22 '11 at 18:22

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