Portal maintenance documents

Question

We outsourced a web based portal and now we're not interested to work with them because the site is becoming more buggy day by day and increase of customers complain.

We've chosen a different team based on their local reputation and their portfolio are good to satisfy our urgent needs. We discussed this project with them and during a week they suggested some good ideas which help us to control. We are agreed to award this project to them. What I am thinking during the transition:

What documents do you think which can help new developers to understand the application? How many kinds of document I can request to them? If a new developers start working on it those documents help them to understand easily of all sides (application, database, configuration etc)

The application is on ASP.NET and SQL SERVER 2005 and the scariest part of all no source control tool is there. They do direct deployments without even push the publish button. Touch Luck :(

Thanks.

Answer 1

That's kind of hard to answer without knowing what kind of portal it is, but what comes to mind:

• Owner's manual: Description of functionality, technologies used, full overview of all machines and services involved (don't forget data bases)

• Backup: How and where is data backed up, where to restore it from in case of a crash

• Description of all Databases used, relations between tables, at least quick rundown on what data is stored where

• Links to any and all URLs to administration interfaces, tools, and scripts

• Day-to-day operation: What cron jobs need to run frequently, are there caches, file lists or other things that need to be taken care of frequently

• Make sure all domains used belong to you and are under your control

• a description of the project's file structure (which part is where; where is the API; where are the visual elements; where are the front controllers)

• How-To's on how to change the visual elements of the site (Style sheets, forms, templates...)

• A description of any and all URL rewriting operations that take place in various parts of the systems, and where they point to

• Which Google Analytics / Google Webmaster account is used and how to get hold of it

• Ideally, an API documentation and full phpDoc style source code documentation

Answer 2

In addition to @Pekka's good answer I'd add the following

• Functional Design Document (or Business Requirements) - One that explains how the application should work from a business perspective.
• Technical Specification (or Architecture document) - One that explains how the application was developed from a technical perspective.
• Application Support Guide - Some form of cheat sheet that explains the common problems, service accounts, batch schedules... etc

In addition to documentation you should be aware of the incident trends;

• How may incidents?
• How often?
• How long do they take to resolve?
• How many known defects are there?
• Who maintains the infrastructure (patching OS, security audits, etc)

If you don't have enough technical resources to cover the daily number of incidents (keeping in mind there might be peak periods when usage of the portal is high) then you will probably find yourself in the same situation as your current service provider.