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.

  • 2
    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.
    – user7519
    Apr 29, 2012 at 2:59
  • 1
    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, 2012 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. Apr 29, 2012 at 9:42
  • if you can't explain what your code does, how can you have written it?
    – jwenting
    May 7, 2014 at 9:24

2 Answers 2


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 https://stackoverflow.com/questions/708624/what-should-a-good-technical-design-document-contain

  • 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.

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