I was assigned to fix some issues in a PHP project. Later on, I was asked to implement some new features, which I did. The project neither uses any framework nor does it use OOP. It lacks a proper structure, except for the use of folders (no sub-folders) to organize files. There was no documentation created by the original programmer. Now, the project's almost complete with some simple testing to be done and the client is asking for documentation.

I have a few questions actually.

  1. I have always considered documentation as a process which is starts before starting the coding part of project and which continues till the end. So, am I wrong about this? Is the documentation done at the end of the project?

  2. What should be my way to go on documenting this project. I've kept a basic "log like" documentation on the changes I've made for my personal use. But since there was no initial documentation produced, I didn't bother to create one either.

  3. Is there a good documentation template that I could use to reduce my effort?

I am talking about or code documentation (not user documentation). Although I'm assuming this since they haven't specified anything.

  • 2
    The worst part: documentation. Feb 14, 2013 at 15:10
  • 3
    Are we talking about user documentation or code documentation (or both)?
    – yannis
    Feb 14, 2013 at 15:12
  • 1
    You mention change logs... are you using version control software? If you're not, start. Right now. Today. Before you write any more code.
    – Daenyth
    Feb 14, 2013 at 15:37
  • 3
    You are just "assuming" that your client means code documentation, but you are not sure? Seriously? Honestly, your first way of "documenting this project" should be to clarify that. No excuses. Next time you meet your client.
    – Doc Brown
    Feb 14, 2013 at 21:10
  • 2
    @rahules And just what the hell does "code documentation" mean? It is a sheet of paper with a single line: "We wrote it in PHP"? Come on man, CHAT with the client and find out what his expectations are. Don't pretend that you or he know what the industry standard is.
    – Philip
    Feb 14, 2013 at 22:24

2 Answers 2


Welcome to the drop-dead boring side of software engineering, reverse engineering products you already have!

This is largely a job to make it look like you know what you're doing and the company isn't incompetent enough to skip a crucial step of the process, even though they are. In theory, any sort of documentation will help other programmers step into the project later, so if you find anything that was confusing to you, write out an explanation about it after you figured it out.

1) You're absolutely right. Most documentation (should) come before the product is made. Things like requirements, design, testing. Others however, are expected to be made afterwards; users manuals, traceability, QA checks.

2) If the customer is asking for it, you should take the dive and produce the documentation they want.

3) There are a lot of different templates out there. Google around for SRS, software requirements specification, SDD, software design description, or even DO-178 templates, if you want to be buried in paperwork till the end of your days.

But by and far, do enough paperwork to make the customer happy, as you've already missed the boat for it's usefulness. Unless, of course, this project has a long life ahead of it. In which case, you should really get on top of it before it grows to something unmanageable.

  • +1 for a good, broad answer dealing with different kind of documentation. But one thing about "manageability": documentation is seldom "the solution" - at least "more documentation" is not always "better". On the contrary, too much documentation can easily become part of the problem (of course "no docs" too). The hard part is to find the right amount.
    – Doc Brown
    Feb 14, 2013 at 15:54
  • I wouldn't say any documentation will help, not even in theory. Incorrect documentation can be and often is worse than no documentation at all. Feb 14, 2013 at 19:38
  • 2
    @whatsisname - Bad documentation is usually a result of becoming outdated. Of course some people are no good at it or don't make enough effort. If they've already determined they're going to write bad documentation from the beginning, they've got bigger problems.
    – JeffO
    Feb 14, 2013 at 20:29
  • @whatisname Instead of blaming docs in general, why not blame managers or developers for not having the time to keep them up to date? Incorrect docs should be fixed, not cause you to dismiss docs in general
    – user7433
    Feb 14, 2013 at 21:34
  • You are right, documentation should begin before you start coding. However, it is a continuous process as the documentation should change with the project.
  • Documenting your changes alone may not be the sufficient. It's good to start with the changes you have made, but even better we if you take time to document the entire code base. I know this can be a pain, but good things hardly come easy.
  • Wikis are a good documentation template . Try DokuWiki https://www.dokuwiki.org/template. Developing in languages like Java makes documentation easier as there are tools that generate documentation from comments in your code. But I am not sure you have the same luxury with PHP.
  • Code documentation should be kept very close to the source code. Either in the source files themselves or in plain text files next to the source files (markdown is fine for this). Wikis go stale because they are not with the source code. Feb 3, 2020 at 22:22

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.