For the last year or so, I have been working on a very large application. I am currently on version 17 of it, and every time, I start over with some of the code from before. But now, this is starting to become unmanageabley large.

When I do the design for the application, I generally start with a Word document, outlining all the classes, with the functions, descriptions for each, their dependencies, default configuration data, and how each component augments the rest of the application. But with that method, within a few hours, I can easily reach 20-30 pages of documentation, and the nice simple outline of the software because so complex in itself, using that as the template to write the code to becomes difficult.

So, now, I am trying to describe the application in an XML format, built on an XSD that contains the structure of how the classes will be laid out. But, this is also demonstrating its problems.

At this stage, everything ahead of the base application has been designed (the database er diagrams, the functionality, etc), but the main problems lies in the design of the underlying software that runs it all.

So, can anyone recommend what path I should go down, either with specific ways to lay out a Word document for easy reading, an XML pattern that would do the same, or some other software package that can do this for me and help guide me through the development?

Any help would be greatly appreciated, mainly because once this part has been cracked, my application can finally be built and completed.



What is the main purpose of the document you are creating. Are you the only developer working on the app or there is a team working with you?

  1. Don't underestimate the power of visual presentation. A picture is worth a thousand words. You could use some of the available UML tools or a basic diagram tool.
  2. Use naming conventions - this will reduce the need to document. For example, with DAO for all Data Access Classes. Then it will be self evident that UserDAO does all the operations pertaining to saving and retrieving user information from database.
  3. Document in detail only what is not obvious.
  4. A quick Google search found PHPDoc. This could help document implemented code
| improve this answer | |
  • This is for me, but will probably have other people looking at it in the future. 1) Absolutely, love the visual representation, but UML sometimes gets just as messy by becoming a great big mass of arrows and connections. 2) Naming conventions are something that I have already dealt with. I know what layout and what Naming convention I am going to use. 3) Absolutely, but sadly, that was one of the first things I cut out, and I was left with 20 pages of docs (down from 50). 4) More for production code, at this stage, the Coding wont happen for a while, but could provide a starting point – topherg Oct 10 '13 at 15:30
  • Have you tried having levels in your UML to keep them from being a large incoherent mass of boxes and arrows. This should help you organize them better. – Maru Oct 10 '13 at 16:37
  • I have, but there are so many cross overs in each level, as well as a mass between the levels. It does feel more like a graph of dependencies of modules on each other – topherg Oct 11 '13 at 8:20

Think of how you can make it smaller! Chuck stuff! Prioritise features and only plan highest priority stuff. Implement that minimum. Getting something small but working might well change all your plans anyway.

| improve this answer | |
  • Oh, I have. I have broken the project down into the core to run the system, the builtin modules (about 18), then as individual plugin libraries (about 22, all together, 130ish modules). And that does become manageable, but when it comes to planning them, as well as their interactions and dependencies, it turns into a mess. But that is the route I am presently taking, and it is getting good – topherg Oct 11 '13 at 18:44

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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