I am a junior developer working on my own in the programming aspect of projects.

I am given a png file with 5-6 of the pages designed, most times in specific detail. From this I'm asked to develop the back end system needed to maintain the website, usually a cataloging system with products, tags and categories and match the front end to the design.

I find myself in a pickle because when I make decisions based on assumptions about the flow of the website, due to a lack of outlining details, I get corrected and am required to rewrite the code to suit what was actually desired.

This process happens multiple times throughout a project, often times on the same detail, until it's finally finished, with broken windows all through it.

I understand that projects have scope creep, and can appreciate that I need to plan for this, but I feel that in this situation, I'm not receiving enough outlining details to effectively plan for the project, resulting in broken code and a stressed mind.

What should be the minimal design/scope documentation I receive before I begin development?

3 Answers 3


when I make decisions based on assumptions [...] I get corrected

Then don't make so many assumptions - clarify beforehand, ask! If the person you have to ask is not available all the time, prepare a list of questions. And repeat that whenever new questions arise, regularly, perhaps daily!

This process happens multiple times throughout a project [...] with broken windows all through it.

When you improve your code multiple times, it obviously should become better, not worse. If your code gets worse, that is almost everytime a sign that you try to add new requirements to your existing methods and classes again and again, without any restructuring of your code, until they got too big or too complicated. You can avoid that by starting to refactor more early. Every new requirement you add should be an occasion to refactor your code along the process so the new requirement can be added more easily. If you need more help, you will find plenty of information about refactoring on this site.

what should be the minimal design/scope documentation I receive before I begin development

Your misconception here is - "someone else writes down all the information for me, then I start to code". When you have asked your list of questions, write the answers down and add them to the spec or design documentation. Then implement what you are sure about, until new questions arises. It is virtually impossible to foresee all the questions you will have for the one who writes the design/scope documentation, so don't expect him to do that. Better see it as an incremental process. When you have no questions any more, and you have written down all the answers you got, then your design/scope documentation is complete.

  • Well that felt like a swift kick up the bum, but you're right. It's a team of two of us, and the assumptions occur as I don't want to irritate my boss, but your suggestion is spot on, I should be making lists of questions. Refactoring is something very new to me, first job as programmer, 6 months in. I'm guessing this is an area I have a lot to learn in. Thanks for the direct, but informative feedback.
    – hoppipolla
    Sep 18, 2012 at 8:54

I think, the fundamental issue is in communication, not in documentation.

In addition, clarifying client and business needs with product owner/BA (or PM if there is no business analysts) in your organization through effective communication will ease your life and in great help you to deliver good results with less dramatic change sets.

As you may also know, Agile Software Development is targeting the mentioned goals above and you may find more information from this reference .


I've found that there is no single answer. No Golden Rule.

Each client and proejct requires different level of specifications.

One thing is vital to all though - communication. To the best of your ability, make the client understand what you are doing and why. Make sure to discuss each aspect of the website and undestand every bit of it.

I would advice you to do the following: - what is the end goal. - what this site does - who uses it - How this site helps the bussiness

Aim to answer those questions before even thinking in terms of coding. After you clearly understand what your client wants/needs THEN forget all about it and focus on implementation.

I had clients giving me a brief 5 min talk to exaplin a system that will take 2 months to display. And I had specifications written on 10 pages that would take 2 days of development.

Its important to remember that we serve a purpose in the client's bussines - we create something for them and we need to know WHAT that thing is

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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