The development team has finished a website and my duty is to prepare a document so that other programmers can maintain the website with ease.

I have no experience in this and would like to ask what should be mentioned (document structure) in that report?

So far my idea is only to prepare a ERD diagarm for the database and flow chart for each function. Any other suggestions, eg. what cookies stored?

closed as not constructive by Walter, gnat, EL Yusubov, GlenH7, Giorgio Nov 13 '12 at 19:50

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance. If this question can be reworded to fit the rules in the help center, please edit the question.


For a small-scale commercial website, it's a good idea to have:

  • Database related documentation.

    Don't forget the SQL file which creates the database. The documentation should also describe the infrastructure itself (for example how frequent are the backups, etc.)

  • Technical documentation (not the user manual, but the documentation which describes things like how the architecture of the application is done).

    If cost is prohibitive, the technical documentation may be missing if the code is clear enough. If, on the other hand, the code wasn't refactored for months, it's a good idea to write at least a short description of the architecture.

  • Original works.

    It's nice to have JPG and PNG images which are actually used on the website, but when the request consists of modifying an image, it's hardly possible (or at least very expensive) without the original Photoshop file.

    The same comes for anything else. As a freelancer, I was asked twice to modify an ASP.NET website with no original source code. Every time, the customer was surprised to learn that it is not possible at a reasonable cost.

    Working with minified JavaScript (with no original source) isn't funny neither.

  • Documentation about the processes, especially the deployment process.

    For example, how the JavaScript file was minified? What tool is used to combine CSS files into one? What version of ASP.NET MVC do I need to install on the server?

  • Legal info (licenses, original source, etc.).

    It is usual a nightmare when you want to determine what is covered by which license. Do I have a right to reuse a content? Where do I find the original author? Who wrote a piece of text on a specific page of the website?

    Also, what are the particular laws which apply to the website? Are there any legal actions? What about mandatory stuff like the choice of tracking cookies in EU?

  • Contact info.

    Who should I contact if I have an issue with the graphics (for example the original Photoshop file is missing for a part of the website)? Who is legally responsible for the website? etc.

  • Security-related stuff.

    Just today, I've received an e-mail from a customer of mine, asking if I can reset the lost root password of the server, given that the root account was created by the hosting provider, and I never used (and never should use) this account myself.

    When nothing is documented, it is not unusual for everyone to use the same account (root) to connect to the server. To avoid such critical situations, documentation should describe the policies related to accounts (who may create them, for whom and in what cases; note that you should never include any password in the documentation), the information about security-critical data, etc.

  • Disaster recovery plan.

    If one day your hosting provider contacts you to tell that all your data was destroyed after your website was hacked or after the data center was flooded, having a disaster recovery plan is sweet. Just ensure that it was tested, and that it is kept constantly up to date.

    Many web apps don't have any, so even if they might have some backups, they are usually unable to recover after a major disaster or spend weeks to recover, since nobody knows the precise configuration.

  • Additional points for having version control (with the history of revisions) and bug tracking system (with all bug reports).

Those are the must have for any commercial website. If you're working on a large project requiring more reliability than just an ordinary website, then Stack Exchange won't help you: there are lots of documents to have, each one being written using specific standards, processes, etc., and the subject is too broad to fit in an answer.

Note that in practice, web apps have no documentation whatsoever. When customers ask me to modify their websites, in practically every case the only things I had was spaghetti code and a short, half-page badly-written description of the project.

The best case I had was a web app for one of the largest French companies: not only I had some sort of requirements (written by a person who never learnt how to write them), but I also had the SQL to create the database structure, and the access to the SVN.

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