What Type of Report or Documentation to Expect from my Programmers

Question

First, I am not a programmer nor do I have any programming experience. I am an entrepreneur that had a website idea and hired programmers to custom build it. It has been going on for the last one year now. It uses Wordpress with some plugins such as Buddypress, Bbpress, etc, but a lot of custom codings as well.

I give the programmers tasks and they do them and the tasks work as I want, but they don't present any report or documentation as to what they did and how it was all coded, etc.

But my problem is - what if they suddenly disappear and I have to get other programmers to continue working on the site? Can the new programmers do a good job of taking over when there's no report or documentation, etc?

Of course there's report from me to the programmers telling them what to do and what functions I expect the tasks to perform. But when done, they don't present me with any report or documentation. They just say the task is done and I check and it's done.

If such report or documentation is required, what type should I request from these current programmers?

Or am I being unnecessarily paranoid?

Answer 1

I believe the problem is not about what documentation you should ask for. It is about how you can check that it is valid and will actually help new developer to pick up where previous left. It is easy for you to check if actual feature works, but not easy to check the documentation, no matter what kind of documentation you will request.

This is how I would do it: first, I would add requirement of exactly what you want. I would say that "Each feature should be documented enough for new developer to get general understanding of it, why it exists and why was it implemented the way it was." I would leave it to developers to decide how best to document their work. They can create comprehensive external documentation or they can make the code itself self-documenting with minimal external documentation. After this, I would hire a different, external developer to do a code review of their work. This developer would "emulate" a new developer and would try to understand the what the application is supposed to do and if it is doing it properly. Then he produces a report based on how easy it was for him. This could be done periodically every few weeks/months.

Answer 2

I think the chances are that you do NOT want any code documentation from the programmers.

The reason you state that you think you might want documentation is :

"Can the new programmers do a good job of taking over when there's no report or documentation, etc"

So the documentation isn't for you to read, its not a manual for the product, It dosnt give you any benefit of itself.

If you don't get new programmers during the life span of your product. You will have paid your programmers to write documents that are never used.

In my opinion, your hypothetical new programmers will probably not read them either. Programmers tend not read code documentation for a variety of reasons and this is generally recognized with modern 'agile' programming methodologies.

So I say, Don't ask the programmers to document their code.

However! What you DO need to document are your requirements, and what tests you ran to ensure they were met.

eg.

Requirement 1: "when there is an error, make the button red"

you need these because the hypothetical new programmers will not know what the code is supposed to do.

Your current programmers understand the project, so when you tell them

Requirement 2: 'Make the button blue'

They remember your previous requirement and they will make the button blue when its not errored and red when it is.

The new programmers however, were not around when you asked for requirement 1. so they will make it blue all the time.

You will have to remember all the requirements and tell them:

Requirement 2 : 'make the button blue, unless it is errored in which case it should be red'

Its impossible to remember all the requirements for even small projects and whats worse the combination of requirements, ie that the red state overrides the blue state is never actually stated. That's where writing down your tests comes in, you will have tested the app worked after requirement 2 and written

"Tested normal page ok, tested error page ok"

This will tell the new developers that the error page is Supposed to have a red button, and its not a bug which needs fixing.

What you need to protect yourself from losing is that big picture of what your application is supposed to do. That's the thing that only exists in your developers heads at the moment and its really something only you can document.

Answer 3

You want a high-level design document that describes the big blocks and their interaction and then functional design that describe how these blocks were implemented. Read up on UML for the main design concepts (but do not make them deliver UML docs, please - they go into too much detail, you only want the overviews)

Often the documentation can be sufficient with a simple text document describing the overall architecture, tools used (and versions!) - just enough to let a new dev understand the concepts and assumptions used which will let him them get into the code to find out the exact details of implementation.

You can demand full-on documentation, I've worked places (police, government) who really need to know exactly how something works, and such doc is a beautiful thing to have - but it rapidly gets more expensive to produce, and I think would be overkill for your needs, so be careful not to go too far in documentation. There's a sweet spot between none, enough to understand the product, and too much.

Answer 4

Hello if i understand you very well you want to be sure when your current programers are no more there to manage your website you can hire someone else and it will be easy for them to write and not re-inventing the wheel. good one.

good programs are to themselves a good documentation, sorry there might not give you a paper documentation but its in the coding, you might not know it but the programmers will. just always remind them to keep proper documentation. when the new programmer comes he knows were to find the documentations.