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 would like to know what options are available for documenting a project which has already been developed, as the developers who worked on didn't write even a single page of documentation.

The project has no other details other than many pages of scripts with functions written and modified by developers who worked on this project from the past 2 years. All I have is the database schema and project files. I would like to know if there is any way to organize this project and document it so that it could be helpful for the developers who will be working on this project in the future.

The project was developed with PHP and MySQL. The functions are poorly commented so I can't get good results when I run it with doxygen.

share|improve this question
2  
I'd start from documenting the workflow. After the big picture is clear, you can add more details. –  superM May 13 '13 at 7:58
1  
Related (though not necessarily duplicate): programmers.stackexchange.com/questions/6395/… –  thorsten müller May 13 '13 at 8:07
    
IMHO a really helpful thing in the beginning is a cross-reference - "where is what?". At least, when it is not obvious from the names of the scripts (and I guess it is not). –  Doc Brown May 13 '13 at 8:42
    
@superM I was thiking to do the same what you just said, I think it is a better idea to document a workflow / functionality before I can start with –  Bala Chockalingam May 13 '13 at 12:16
2  
The functions are poorly commented so I can't get good results when I run it with doxygen. Try running it with a debugger. That will explain what it does a lot better than having a copy of the comments with the source code removed. –  Mathew Foscarini May 13 '13 at 15:08
show 2 more comments

4 Answers

up vote 17 down vote accepted

Who will be reading the documentation? What will the documentation be used for? These are the most important questions to answer. For example, documentation for maintenance developers would focus more on structure whereas documentation for developers integrating with the product would focus more in web services and database structure.

In general, do as much documentation as is required and no more. Many organizations require documentation because someone insisted it is best practice but the documentation ends up gathering dust.

Assuming that people will actually use the documentation, do not try to capture the code and database to the smallest level. Developers will look at the code for minutiae. Instead, focus on details that are not apparent in the code, for example:

  1. The use cases the product meets. This may be difficult considering the age of the product but capturing what the product is meant to do gives vital context to non-technical readers and testers. Who are the competitors in the market (if any)? Is there anything excluded from the product's scope?
  2. Any clear non-functional requirements. For example, was the product written to handle a certain volume? How old can the data be? Where is caching used? How are users authenticated? How does access control work?
  3. A context diagram showing interaction with other systems, such as the database, authentication sources, backup, monitoring and so on.
  4. (If known) Risks and how they were mitigated along with a decision register. This is probably difficult in retrospect but there are often critical decisions that influence a design. Capture any that you know.
  5. Common design patterns or design guidelines. For example, is there a standard way of accessing the database? Is there a coding or naming standard?
  6. Critical code paths, usually using flow charts or UML activity or sequence diagrams. There may not be any in the project but these are usually ones business users have articulated.

Even if all this information is not available, start now. The developers that come after you will thank you.

Good automated unit tests or test cases can also be useful documentation, albeit hard to access for less technical people.

It also sounds like you need to make a cultural change to include documentation. Start small but, ideally, the project should not be "done" until it has at least a minimal level of documentation. This is probably the hardest step because the above are things you can control. This is something others must buy into. However, it can also be the most rewarding, particularly if the next project you do comes with good documentation. Good luck!

share|improve this answer
1  
+1 for the first 2 sentences alone –  jk. May 13 '13 at 13:41
add comment

In the past I have managed a situation like this by sitting down with the various product owners or power users, going through their primary use cases and documenting these with a set of tests. You can use these as a baseline for the system when you begin to make changes in the future. This can also help identify areas of the system that do not have an owner or use case and are may potentially be deleted.

It all depends on the size of the system really. If this is a complex system with many different stakeholders you could create a high-level component diagram detailing what capabilities exist and where they are satisfied. This can be very helpful to identify architectural issues in the system design.

In general I suggest avoiding old-fashioned documentation because it will get out-dated and it will miss-lead developers in the future. I always try to produce living documentation in the form of tests that will be maintained as the system evolves.

share|improve this answer
add comment

First things first, who is your target audience? Future developers or other businessy people? With the answer to that question in mind:

As others have said, a high level description is the first thing you need. Explain what the system is trying to do in the broader scheme of things. Explain what it runs on, how it fits into the network and talks to any other system. Then I would go through each screen, screenshot it and give a quick explanation of what the screen does, and how it interacts with any other parts of the system. If its for developers, keep it conversational like you are explaining the app to them for the first time. After all, that's the point of the doc (I assume).

Any complicated processing or logic I'd use a state diagram, data flow diagram or sequence diagram. Definitely do an entity diagram, then a DB schema design (two different things!). Maybe a basic class diagram but keep it simple, only note the main stuff that's of interest, devs can figure that stuff out by looking at the code.

If you're having troubles getting started, just pretend there's another developer there in the room right next to you, who doesn't know the first thing about the system, I relatively impatient and just needs to know the gist of it. Then start explaining, and write down what you say :)

share|improve this answer
add comment

The previous suggestions are all good ones, but I would also consider researching if your community of users have created any ad-hoc documentation themselves. Your question did not specify whether any version of your 'product' (existing for two years) has ever been released to users. If it has been in use, and there is no official documentation, then either no documentation has been necessary, or there is somewhere 'unofficial' documentation which may be rudimentary, but also probably perceived as essential by users. Try searching the web for artifacts likely to represent critical APIs, search forums, ask power-users, and search question and answer sites. If possible, try to write documentation that is fulfilling a technical or business need.

share|improve this answer
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.