Whenever I am submitting an article for publication, I like to take a look at the various items I am currently working on and write the article based off of my real-world experiences. It just so happens that, at this time, I am working on documenting a workflow solution that we created to manage an HR onboarding process. During my work this morning, I realized that it would be a good reminder to encourage everyone to document as you go!
When SharePoint is first implemented, documentation seems to be in abundance. Whenever things are configured or added, it seems natural to document and record what has been done. If you fast-forward a few months, though, the documentation seems to be lacking. Think back over the past six months and the various quick solutions you have built using SharePoint. Now, out of all that you can think of, how many did you take the time to document?
Your documentation doesn’t always need to be in-depth or extremely detailed, but it should at a minimum serve as a reminder of what you did when you look back on it eight months from now because you need to make a change. It should also give any new resources a good idea of what was built and how everything is configured.
To help you get started, I am going to share with you one of the sample outlines I use when documenting the different solutions that I build.
I. Project Description: In this section, I describe the business problem that is being addressed. I also make sure to list my stakeholders and resources. As the project completes and evolves, this list is updated to include any additional resources.
II. Site Design Summary: In this section, I provide a summary of the site layout. This includes who the primary users are and what they are accessing. I often include screenshots of the completed solution as well to make it easy to reference for anyone who is reading the documentation and comparing with the solution.
III. List & Libraries Summary: This section contains a summary for each list and library that is included in the solution. I record the purpose of the list along with the permissions assigned to the list, the content types associated with the list, and any workflows that run against the list.
IV. Workflow Summary: In this section, I map out each of the custom workflow processes. Depending on the complexity of the workflows, process diagrams may also be included. This is really just to be sure to record what the overall purpose is in the workflow and document what elements it provides to the solution.
V. Change Log: Finally, I wrap up the documentation with a section to record the major changes to the solution. In this section, any updates are recorded and summarized. Then, as needed, the other sections of the document are updated to ensure they contain the most up to date changes. Keeping a change log in the back of the document helps me to ensure that we are aware of the various changes that have occurred over time.
I know that this is a very simple outline and that it doesn’t apply to all solutions that are built in SharePoint. The point is not really to say “do it this way” or to give you an outline that can be used in every scenario. Instead, my goal is to get you thinking about the various things you build in SharePoint and encourage you to document them as you go. They may seem small and manageable now, but what about six months from now or two years from now? Will you remember what you built or why you added various lists and workflow actions?
Taking a few minutes today to document will help save you time in the future. Take my word for it: Documenting solutions as you go is much easier than reverse-engineering them when you need to make an update to the existing solutions!
Jennifer Mason is a consultant at SharePoint911 and a Microsoft MVP. She writes regularly for SPTechReport.