SharePoint Beach Volleyball

I’m sorry, but if I made the title of this blog “Documenting SharePoint”, would you have even started to read it? I didn’t think so. Documentation is a term with a bad history. Writing documentation is often considered a crummy job, and reading documentation often provides only marginal benefits. In both cases, I would argue that the product was ill-conceived. Well-designed documentation can be very useful and if the task is approached properly, it really isn’t that hard. If you’re saying to yourself, “he probably isn’t the guy actually writing it”, you would only be half-right; I did right some of it.

If you’re saying “SharePoint solutions don’t need to be documented”, you would be half-right again. I am not talking about creating virtual binders of User Documentation. SharePoint solutions are seldom intuitive, but if you are primarily using out-of-the-box solutions, as we are, SharePoint should become familiar with use. Even if you are jazzing your program up with a bunch of JavaScript, JQuery, third-party web parts and custom branded solutions, your users should benefit from a consistent site-to-site look and feel. If SharePoint is being used to automate a business process, it should be documented along with the process, but that’s not what I want to talk about today. I want to talk about documenting your solution so your successor knows what you did, and why you did it – even if your successor is your future self.

We finally put our time tracking “system” to bed last week, and the last thing that we did was to finalize the documentation. When we started this project, we were undecided as to how we were going to document it. To keep us from getting too far into the project and then having to backfill our documentation, we started describing things like Lists, Forms and Workflows in OneNote. We wrote simple descriptions of key elements, and we included screen shots of the trickier settings. The more we used OneNote, the more we liked it and we came to the conclusion about mid-way through the project that it was the right tool for the job. It wasn’t just that we liked what we saw; we actually had to rely on the documentation we had created. For reasons beyond the scope of this post, we decided to relocate the SharePoint site associated with this project. Everything went fine, except that the workflows didn’t migrate with the lists. We investigated solutions, we tried different things but finally, we decided it would simply be easier to recreate them. Having documentation made that an easy process.

This is more than an anecdote; this is a powerful two-part lesson. First, documentation can become necessary without warning. Second, the best time to produce documentation is during development. OneNote makes the second lesson easy to heed. Once you get comfortable with what to put in Notebooks, Sections, Sub-Sections, Pages, etc., OneNote is surprisingly easy to use. My favorite thing about OneNote is that you can put anything anywhere. Text, lists, images, screen shots; anywhere on the page without adjusting wrap settings, messing with page settings and worrying about where the letter will appear when you start typing. OneNote also automatically synchronizes the changes of multiple authors; it is editable in a browser view in SharePoint and on Microsoft Live.

Some people may bemoan OneNote’s limited drawing and formatting tools, but I actually put these limitations on the plus side. I have produced documentation in Visio, for example, and the tools are so tempting that you can spend hours trudging beyond “good enough” in pursuit of perfection. Documentation doesn’t have to be produced at the molecular level; it just has to explain what you have, how and why it works. We start with an overview of the solution concept, and then we describe the lists, the views, the forms and the workflows. We include formulas for calculated columns, validation criteria, sort and filter parameters and the selection criteria when workflows lookup values in lists. We also describe the permissions required for the users in various roles. Of course, these are all things you can look up quickly in SharePoint, but you have to have permission and you run the risk of changing something. Besides, I have a strong aversion to using production environments for anything other than the task there were designed for. Also, you can’t lookup “why” you did something. One of the reasons I document why things work, is in anticipation of SharePoint continuing to improve. For example, the project we are currently working on includes a list whose only purpose is to trick a workflow into iterating over another list. When Microsoft adds loops into SharePoint Designer, we can lose the second list.

SharePoint is a long-term solution for our company, so documenting our custom solutions is critical. If our project isn’t documented, we are not done!