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.
-
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?
-
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.
-
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.
10
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.
4
- 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.
1