Documenting SharePoint deployment and/or customization projects can be even more of a hassle than documenting a standard software development project. Gasp! Did I just say documentation was a hassle? Yes I did, and it is. Therefore, let’s make sure our documentation serves a purpose and brings value to the equation.
With SharePoint development, it is often difficult to distinguish the custom code or configuration changes from native SharePoint functionality as they work together to provide great features for your customers. Once this distinction is made, one must decide how much of the native functionality needs to be included in the documentation to provide a coherent description. As with most documentation efforts, the key lies in identifying the intent of your documentation as well as your target audience. Add a dash of organization and voila! – Valuable documentation arises from the clutter!
For all but the simplest SharePoint development efforts, the scope of documentation needs to include more than just a description of the code changes. Your projects may need to include the following types of documentation:
-
Customer Profile
-
Proposal
-
Requirements
-
Functional Specifications (we fold these into the Technical Design document)
-
Technical Design – Approach
-
Development Plan
-
Test Plan
-
Technical Design – As Built (code changes are described here)
I should also mention that this entire list is affected by the inherent peculiarities of SharePoint customization. But don’t worry; we can do this, just keep your focus on the intent and on the target audience. The dash of organization applied here will be to group the documents by project phase.
Proposal Phase
Discover Phase
Note: Functionality should be described using a list of “well-formed” requirements:
http://spacese.spacegrant.org/uploads/Requirements-Writing/Writing%20Good%20Requirements.pdf
Up to this point, your SharePoint project looks very much like a standard software development project. We have engaged the customer and determined what they want. As the project moves into the Design & Build phases, the intent of documentation becomes multi-faceted and the character of the SharePoint platform has a stronger influence on how that intent is achieved most efficiently.
Plan Phase
Where are the Functional Specifications?
With the SharePoint platform, we are customizing and extending functionality based on a pre-existing design. When documenting the Functional Specifications for SharePoint projects, we want to accept the existing design so that we can specify, in a concise manner, the mere delta that represents our customization. So within our Technical Design document, we outline the native SharePoint architectural features to be utilized and then describe the custom functionality that will extend that architecture. This usually takes the form of descriptions of custom columns, content types, lists, forms, and navigation terms planned for development of the solution.
Build Phase
Deploy Phase
Other Documentation
User Training Materials
User Training Materials can vary greatly depending on the solution. Since SharePoint is a working application out of the box, let’s not forget that we can take advantage of 3rd Party providers of SharePoint training.
Migration
The historical evolution of SharePoint includes some version gaps that may need to be spanned with a migration effort. In this case you will want to develop a migration plan that describes how old content will be mapped to the new environment and a log of the resulting migration activity.
Status Reports
Your sponsors will probably want regular updates. Keep it simple, but include any risks that crop up and require mitigation. We usually report percent complete by phase and manage the WBS schedule internally.
Phase Closure Presentations
Upon completion of each project phase, the scope of work for future phases is validated and any proposed changes are clearly stated in the Phase Closure presentation. The Statement of Work in the proposal is then updated with any scope changes that are agreed upon.
Customer Issue List
There is also a Test Phase, during which the customer will need a mechanism to convey issues back to the development team. Issues should be assigned unique identifier as soon as they are created and include enough detail so that they can be recreated within the development environment. Issues may go back and forth a few times and should include a status column and accommodation for notes.
Lessons Learned
We need to learn from our mistakes, but this documentation also includes those really neat tips and tricks you discovered during the development effort.
Enhancement List
Can you say “follow-on work”? Your customers can and the Enhancement List is a great way to encourage this.
Summary
SharePoint development can feel like tinkering at times, and this has a tendency to discourage the creation of formal documentation. Establish a documentation process to counteract this effect and you will avoid some pain down the road, guaranteed.
Share
