11

I have completed a web application which is basically developed in PHP and is just another regular web application. Usually when I deliver the final production release I just handover the code documentation and the architecture information to the client. However, for this particular project the client insists on having the complete in and out data about the project.

So I'm just wondering... What are the mandatory technical and non technical docs that I can give my client apart from the code and architecture documentations ?

(Also it would be kinda cool to hit the client about various stats and data about the project so that he would actually know the amount of work involved and how cool the product actually is.)

Jalayn
  • 9,789
  • 4
  • 39
  • 58
swordfish
  • 319
  • 1
  • 2
  • 8
  • 8
    Which mandatory items the customer gets entirely depends on the contract and your country's law. – Falcon Sep 01 '11 at 14:38
  • 2
    Why is this not specified in the contract? All documentation created should add value (or at least perceived value), for you, for future developers, or for the customer. You (should) know what documentation adds value for yourself and future developers, so ask your customer exactly what documentation is needed to add value, put it in the project plan, and get it signed off on. – Thomas Owens Sep 01 '11 at 15:25
  • Which ones does the client **wants**? Can you get feedback from a client's technical manager? Also: in which sense is your product "cool"? Could you clarify that? – ZJR Jul 25 '13 at 18:37

5 Answers5

9

I think the list should include:

  • The non-technical requirements (there was such a document, right?)
  • The technical requirements
  • A "decisions" document (if there was one) explaining why some decisions were made over others. This might already be in a different requirements or architecture document, but we usually do this separately for Big Decisions.
  • The code and other resources (image files, CSS, etc...)
  • The database model (as a diagram, document, whatever)
  • DDL to create the database.
  • DML to seed the database.
  • A document explaining application setup and basic trouble shooting.
  • A list of any important usernames and their passwords (for Admin accounts), as well as instructions on how to change the password. Ideally, when they set up the website for the first time, they should be prompted to enter a new admin password, but this is more of an architecture thing.
  • System requirements, and for web apps, minimum hosting requirements as well (Does the app need MySQL or PostgreSQL? How much RAM?, etc...)

Not all of these things might be available (or necessary) for every project, but I think this is a good general guide.

FrustratedWithFormsDesigner
  • 46,105
  • 7
  • 126
  • 176
  • *"A list of any important usernames and their passwords (for Admin accounts)"*: really? The developer should **never** know any password once the website is released, especially administrators one. If you give to the customer the list of passwords you used during development, you may be sure that the customer will never change them. – Arseni Mourzenko Sep 01 '11 at 15:06
  • 4
    @MainMa: I assume that the client has the ability to change passwords, and that one of the first instructions is "Change your passwords!" – FrustratedWithFormsDesigner Sep 01 '11 at 15:19
  • could you please clarify for the novice what are "non-technical requirements"? – Abe Jul 19 '13 at 00:27
  • 1
    @Abe: The non-technical requirements would say something such as "This application should let a user manage their own accounts" and the technical one might say "SOAP-based web services will expose an interface that allows the client application to manage user accounts". – FrustratedWithFormsDesigner Jul 24 '13 at 13:42
4

In addition to the really good answer of FrustratedWithFormsDesigner I'd like to say what the non technical documents include (as we did it):

  • the analysis data: what did the customer tell you when you first talked about requirements?

  • the offer you made:

    • the product requirement document
    • and the functional specification document

    which together act as a sort of contract about what you must do and what you expect
    the customer to deliver during development as well as the estimated time and cost.

  • the specification including review protocols, usecases and testplans, testresults

  • the design in UML and all corresponding documents

  • the documentation of sourcecode (doxygen or whatever)

  • the manual and installation guidelines

  • the final actual amount of resources (time and money) used for the project, so you can write an invoice

  • some customers want the meeting protocols, too which is then an extension to the "decisions document" mentioned above

Hope that is what you were looking for.

AnyOneElse
  • 227
  • 1
  • 4
3

Follow whichever documentation is applicable for your project from the following.You may already have some of them.

Technical documentation:

  • Details about PHP and information on how it is useful for the project
  • Details about the back end and information on how it is useful for the project
  • Information on Database connectivity along with suitable pictures depicting the flow of data
  • Information about other programming languages or applications involved in the project like XML,HTML etc.
  • FAQ Help file

Prepare documents with screenshots and highlight the relevant code (if necessary) for the following:

  • Information on the front end application like objects or controls,object properties etc.
  • Information on Database queries(if its not already present)
  • Information on Database properties like Primary Key,Foreign Key etc. and how they ensure data consistency and accuracy.
  • Detailed guide throughout the project by using screenshots of all possible kind of screen using both the front end as well as back end after running it with sample data,without repetition of similar kind of data or screen,in a logical order.

  • Input invalid data and show that is impossible to do so as you have done data validation at the front end and back end.
    /* This step is not applicable if you have not used any object for getting direct input from the user like Text Field as it is obvious that you cannot get invalid data through indirect input. */

  • Show that there is no error in the program or inconsistency in the data if there is a sudden failure in the server or client system by explaining the relevant code.

  • After giving sample data through the front end,you can include sample queries in the back end for direct retrieval of data from the server and also include sample DML queries which can help to prepare vital statistics of your data.

You should check these for yourself before documenting them so that if your client asks for a demo with sample data,you can show how the project actually works.Also,make sure that your front end code has appropriate comment lines.

  • Finally conclude with the statistics like total number of lines of code,total number of days spent towards the project,total number of times you have checked the project,a list of all applications used and other technical and non-technical information.


    Non-Technical documentation:

  • Licensing details of project,if applicable.
  • Commercial aspects of the project,if applicable.
IndRaj95
  • 41
  • 3
2

Be Wary

The potential documentation that you could give the client is virtually endless. Additional time required to generate documentation you don't already have is unpaid.

Why does the client want this documentation (over and above the source code)? What will be done with it? Who is it for?

The answers to these questions will help narrow the scope of what to deliver.

It is critical that you and the client agree upon exactly what documentation to deliver, and whether any additional effort will be compensated.

Don't play guessing games. Most technical documentation would be useless to the typical (non-technical) client.

Community
  • 1
Steven A. Lowe
  • 33,808
  • 2
  • 84
  • 151
1

I'd probably break this up into a few document categories:

Guides:

  • Installation guide, the how do set this up on a server.
  • Administrator's guide, for how to configure and run the application for optimal performance. Security would also be something to cover here just so that it is known what passwords does this application have and use to run.

Support:

  • If there are problems, what kind of procedures would you suggest? Are you providing support for some period of time? I'd probably still give a guide or two in this area just so someone else knows some of the easier things to try like restarting services or rebooting a server.

Integration points:

  • Are there 3rd party integration points for this application that make it rely on other vendors than your code?
JB King
  • 16,795
  • 1
  • 40
  • 76