Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
2  
The worst part: documentation. –  Florian Margaine Feb 14 '13 at 15:10
3  
Are we talking about user documentation or code documentation (or both)? –  Yannis Rizos Feb 14 '13 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 '13 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 '13 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 '13 at 22:24
show 5 more comments

2 Answers

up vote 9 down vote accepted

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.

share|improve this answer
    
+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 '13 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. –  whatsisname Feb 14 '13 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 '13 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 –  omouse Feb 14 '13 at 21:34
add comment
  • 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.
share|improve this answer
    
Thanks for informative the reply. –  rahules Feb 14 '13 at 19:56
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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