How to Document an Already Developed Project

documentationproject-management

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.

Best Answer

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 on 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.

Related Topic