Documentation is important aspect of any project. Proper documentation is considered as one of the key element for
- Smooth execution and Success of the project
- Helps in transitions during project lifecycle
- Helps in planning for enhancements in the projects
- Helps in integration across multiple platforms
These are just few benefits of proper documentation, there could me many more.
So what is proper documentation?
This is question we often face in our projects when client complain that document is inadequate we need more information or we were not able to configure the project following this documentation.
There are several theories on what is proper and adequate documentation. These theories are often based on timeframe of the project, based on technology employed in the project, based on various stages of project lifecycle and others. No matter your project falls under which theory, it is very important to determine the document needs of your project, what constitutes minimum set of documentation, what is adequate documentation and how to create right documentation the first time.
Based on my experience executing several Drupal projects I've identified few things that should be there in your document that would fulfill all the criteria of a Proper and Adequate Documentation for your Drupal Project. It would serve as a Technical document that would satisfy the needs of your Client.
- Drupal Version & Distribution: There are multiple Drupal distributions available, from drupal.org, from acquia, pressflow and many others. It is always important to mention which Drupal Core Distribution you have used to build the solution.
- Modules & Libraries list: Prepare a list of all contributed or custom modules you have used or developed in your Drupal site with their versions, also add one or two lines of description. Also prepare list of external libraries you used in your project and explain the reason why are you using it.
- Patches: List all the patches you have applied to the core or the contributed module you have used in your Drupal site. Provide proper reason for using the patch and if possible also provide the links from where you have downloaded the patch. Make sure to commit the patche files in patches folder of your Drupal site, you will need to create this folder.
- Content Types: List all content types with details of their fields, you have created in your Drupal site. Explain the purpose and use of these content types.
- Taxonomy: List all vocabularies created for classifying your content types. Also, mention the terms of vocabulary wherever possible say Vocabulary having finite set of terms. For free tagging vocabulary it does not make sense to have list of all terms, however do mention that vocabulary is a free tagging and used by which content types.
- Theme: Mention in your document which theme you are using and mention if there are some Theme specific Settings. Describe Theme regions and mention in which template files these have been used. Block configuration also forms part of theme configuration, mention all static blocks or blocks generated by module/views, specify in which regions these should be enabled and if there is any visibility criteria then do mention it in your doc.
- User Roles & permissions: Explain how many roles are defined in your solution. List all user roles with their the permissions that are assigned to these roles. Sometimes if there are lot of permissions, you may also want to take screenshots and put it in the doc for reference.
- Menus: List all menus and briefly describe their purpose and region of use.
- Module specific configurations: Here list down all module specific configurations. If you are using Imagecache module to resize images on frontend then list all presets you configured for your solution. If you are using WYSIWYG editor you may want to list the profiles you have created for different roles.
- Deployment Process: Explain how the site can be deployed to PRODUCTION Environment.
All 10 points applies to most of your Drupal based web development projects, be it new development, be it enhancement. If your project is an enhancement then add only those details which are applicable to your current development rest can be mentioned as NOT APPLICABLE.
If your document has all these details then be rest assure, it is ADEQUATE, it is SUFFICIENT. This would be good to serve as technical document, architecture document and even Drupal aware client would understand this.
