5

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?

  • Sharing your research helps everyone. Tell us what you've tried and why it didn’t meet your needs. This demonstrates that you’ve taken the time to try to help yourself, it saves us from reiterating obvious answers, and most of all it helps you get a more specific and relevant answer. Also see How to Ask – gnat May 14 '15 at 7:20
  • what kind of report do you want or expect - if you think about it, you need design documentation that describes what they've done, and in rough overview at least, how they went about it. – gbjbaanb May 14 '15 at 7:27
  • @gbjbaanb thanks for your question but the problem is that I am not a programmer, so I don't know what type of documentation or report another programmer would need to understand and continue working on certain aspects of the site. That's why I am asking other programmers/developers here. – Mr Ley May 14 '15 at 7:35
  • I understand the problem - non programmer wants to know what kind of doc a dev would want to get up to speed on a new codebase so I don't understand the downvotes. – gbjbaanb May 14 '15 at 7:40
  • @gbjbaanb FWIW knowledge-transfer tag over here provides plenty stuff to learn about involved issues prior to asking – gnat May 14 '15 at 7:42
4

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.

  • Thanks a lot for your thoughtful answer. Yes, hiring a different developer to do code review, to see if he understands the codes/process sounds like a good idea. Any idea where to find such developers? Thanks again. – Mr Ley May 14 '15 at 8:07
  • @MrLey Sorry, I don't know. That is highly local question. There probably is some local SW contractor company nearby. And even remote contractor might be good idea. It would increase the isolation between you actual developer and one doing the review, increasing "realism". – Euphoric May 14 '15 at 8:09
3

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.

  • Thanks a lot, Ewan, for your detailed response, but I am not so sure I got all you were saying. I read it more than 3 times but not so sure. Can you please explain a bit more? – Mr Ley May 14 '15 at 15:10
  • it was badly worded, I have updated. I hope this makes it clearer – Ewan May 14 '15 at 15:23
  • 1
    Yes, it's very clearer now. Thanks a lot, Ewan. Makes sense what you explained so comprehensively! – Mr Ley May 14 '15 at 15:41
1

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.

  • thanks a lot for your very helpful response. I will surely read up on UML after typing this. A follow up question through... As a programmer, your recommended "simple text document describing the overall architecture, tools used, (and versions)"... is that enough for you to understand and pick up a project from where a previous developer left off? – Mr Ley May 14 '15 at 7:52
  • It depends what's in the document. I have written and read such things - they can be useful, but it really varies according to the complexity of the product and the detail in the document. Its certainly better than nothing as it gets a new dev over the initial hurdle of "where do I start?" – gbjbaanb May 14 '15 at 9:01
-1

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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