How to document a project which is already developed?

Question

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.

Answer 1

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.

Answer 2

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.

Answer 3

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 :)

Answer 4

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.

Answer 5

The question is, do you want to document it as it is now or as it should be?

What I have read from your question is you are thinking about API documentation and not so much user documentation and the code is perhaps not so well maintained and cryptic.

I am afraid if you document now, you will end up throwing most of your work away, once the code is refactored.

I would take the following approach:

• make documentation unnecessary as much as possible by adhering to common best practices. Choose good class names, method names, variables names that you can intuitively understand
• break down huge monster classes and / or functions where it makes sense
• use PHPdoc comments - you can use tools to create API documentation
• write tests for it: The tests will help you to understand or define what the code should do.

Now, you still have things undocumented: this may be the general concepts, the architecture etc. For this, I would actually write documentation - but only write what is really useful and helpful.