In my previous posting, “SharePoint Solution Development, Planning for Success“, I wrote about how the lack of a clear definition and design will almost undoubtedly impact the success of a SharePoint solution development effort (and just about any other development effort for that matter.)

In this posting, I will share with you some guidelines regarding what to include in your definition (scope and business requirements) and your design. The list is by no means complete (hence the term guidelines), and everything on the list will not apply to every scenario. Feel free to contribute your own guidelines and lessons learned.

Note: The following guidelines do not cover topics having to do with Governance or Information Architecture, there is plenty of information available on those already (check out: New governance content for SharePoint published on TechNet and  SharePoint Governance – Key to a Successful Deployment on the SharePoint Team Blog.) These recommendations are meant to compliment that work, which I believe is equally as important.

So to what extent do we define? This will vary per solution, organization, and how much risk you are willing to take. At a minimal your definition should include a list of requirements that the business owners and project sponsors are willing to sign off on as the ultimate factors in determining the success of the project.

  • Meet with a representative of each of the primary roles; a system administrator, site owner, an author, editor, a contributor. Have them describe what they expect to do with the system keeping the focus on the “what” not the “how”. Your more complex scenarios may depend on additional roles, be sure you include those as well.
  • Document the functional and non-functional aspects of the current solution (if one is already in place). Don’t just focus on the negative aspects of the current solution, also look at (and document) the positives. Your solution should improve on the negatives without taking away from the positives.

    Note: Keep in mind that the current solution may be a manual process. If so, document it as well

  • When performing an upgrade, you may think there isn’t much to define.  Remember, we don’t want to take away functionality so its important that we capture what they have. At a minimum your scope and requirements document should include:
    • An inventory of the custom and/or modified site definitions, libraries and lists, as well as the sites that are using them (running prescan.exe will give you most of the site definition information you’ll need.)
    • An inventory of Content Databases
    • A list of unghosted pages (also generated by prescan.exe)
    • A list of any custom web parts
    • Custom Application and/or Administration Pages
    • Try to identify any applications that may be leveraging SharePoint via its web services.
    • Anything else being used that didn’t come out-of-the-box.

The design is more tricky, this is where I find that most projects fail; not always because of a poor design,  more often a lack of one. Do not confuse your scope or requirements documents for design documents. Every project needs a design. If the design seems obvious, then it shouldn’t take you long to write it down before you start doing the work.

For a standard/out-of-the-box implementation your design document should include:

  • A list of web applications that will be created including those for Central Administration, Shared Service Providers, and My Sites when applicable. (Alternatively these can be included in an infrastructure design or build out document)
  • The names and parameters of your content databases
  • A list of Site Definitions that will be used
  • A list of initial site collections and/or sites that will be created including the corresponding site definitions and content databases.


  • The SharePoint Lists and Libraries that will be created for each one of the initial sites
    • The columns that will be created with those lists or libraries in addition to the ones created out-of-the-box
    • The relationships between lookup columns and lists
    • Any associated workflows
    • The document templates
  • Any Content Types and Site Columns that will be created
  • Any Custom Groups and the corresponding permissions they will be given
  • The Content Sources, and Search Scopes (when applicable)
  • Custom Profile Properties and Property Mappings (when applicable)
  • Custom Managed Properties (when applicable)

Note: Always keep in mind that SharePoint is not a relational database and make sure the business clearly understands the risks involved with such designs. Recommend an alternative approach if you feel its the right way to go. Document your recommendations and any assumed risks and have the business users sign off on them.

When performing an upgrade make sure your design document includes the SharePoint 2007 equivalents of any custom web parts (some 2003 web parts may not be compatible), application pages, site definitions, list and libraries, that may have been created for the SharePoint 2003 environment. It may be a good opportunity to put governance in place and rethink the information architecture. Take a look at “Good SharePoint Upgrade Articles and Posts” from the SharePoint Team Blog.

For other scenarios requiring customizations or custom development such as; application pages, custom workflow’s, event handlers, and features; your design document should include the following in addition to the above mentioned items.

  • Document the methods and objects you’ll use in your custom application pages, web parts, and event handlers; making sure you understand the limitations ahead of time. Try to limit the number of assumptions you make by referencing the SDK as often as necessary. Consider using diagrams whenever possible.

    Note: Try to use the out-of-the-box web parts rather than developing new ones, you may find that there is little you cant do. Look to the Business Data Catalog and corresponding web parts. If the web part is going to be used for configuration purposes, consider using a custom application page.

  • Create use cases for your Visual Studio and SharePoint Designer workflows , documenting what the system should do and how its going to do it, not just the users. 
  • If your solution includes InfoPath forms; document all the groups and fields. Specify their name, type, and whether or not the group or field is repeating. Indicate which fields will be published in SharePoint.
  • Document how your solution will be packaged, consider creating multiple packages to separate unrelated Features, Application Pages, and/or Site Definitions.

Remember to keep the users involved, they’ll take ownership in the solution and be a lot more understanding when problems arise.

Technorati Tags: SharePoint, WSS, MOSS