Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

I was asked to create for a freelance project a Monopoly game in Java. After finishing it the same guy asked me to create four UML diagrams from which he could understand how the game works. Everything went well this far but his third request presented me with some problems.

He now wants me to write for him in about 20-25 pages, how the game's code works, so he can understand it. I have been programming for about a year and I was never asked to do this before. I don't even know where to start to do this, from which portion of the code should I start to explain it? I basically suck at writing.

Is there any guide that could help me achive what I need? I've already created the use case diagram sequence diagram, class diagram and activity diagram.

share|improve this question

closed as too broad by MichaelT, GlenH7, gnat, Dynamic, JBRWilkinson May 11 '14 at 20:04

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.

Welcome to the rest of your life, scope creep like this is one of the first things you should learn about; so you can nip this in the bud in future dealings. I hope you are charging for all this add on extra work, especially the the last part, this is not standard at all. – Jarrod Roberson Apr 29 '12 at 2:59
you might want to make sure that you don't fall into the issues discussed in another question at P.SE: My boss wants a narrated line-by-line English explanation of our code – gnat Apr 29 '12 at 9:24
@gnat while the request in the question that you are talking about seems really unreasonable; in this case the client just wants a document about the design of the software. I think here we are facing two different situations. – Vitalij Zadneprovskij Apr 29 '12 at 9:42
if you can't explain what your code does, how can you have written it? – jwenting May 7 '14 at 9:24
up vote 2 down vote accepted

I guess that what your client asked you is the Software design document. You can find some guides here, here and here.

A related question is

share|improve this answer
  • Diagrams that you have created would verify the business logic, but this is something that they already know, so I would question a need for these diagrams.

  • If they are paying for your time and you feel that you can explain your work in 25 pages, then do it.

  • You could ask them to debug code and make a list of questions for you.

  • You could also spend a day with them explaining what you have done.

share|improve this answer

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