Document your deviations

Documentation-Dude

When we were designing the new SharePoint intranet, some things needed (?) to be customized. And you know I am a big fan of custom functionality. (NOT)

  • Formal Publishing sites needed to resemble our internet site (I have always wondered why people think that is a good idea)
  • Collaboration Team sites home pages showed the security classification of the content, the audience and the site owner. (Useful! If applied correctly…)
  • We added another permissions level to avoid site owners creating subsites.
  • The document content types had 20 fields of hidden metadata in them, as per our term store. This was to improve the search experience – after all, in a 40.000 employee company with many locations, a few metadata would be most helpful to find the document from the correct business, function or location.

Dude, where’s my documentation?

So, when the intranet was ready to launch, and support was handed over to the regular support team, the Support team manager asked the developers for all the documentation.
It was not there and they had not planned for it. Against the advice of Veronique Palmer, he accepted this as a fact and support was handed over to the support team. After all, one of the developers was in-house so we could always turn to him.

Or so we thought, as he left the organization shortly after launch of the intranet…

Support

Support mostly went OK as the majority of issues had to do with permissions.
But when the content types started to show issues we had no clue where to go for help, so we ended up installing the regular content types. Nobody wanted to complete 20 metadata fields for each document!
And when the organization changed structure, the metadata changed as well and nobody knew where to make the changes in the content types.

What to document?

So, while I agree with everyone that too much documentation is a waste of time and effort, it DOES make sense to document:

  • Any custom functionality. What is the customization supposed to do? What are the specific settings? Is this set by tenant, site collection, or site? Where are the settings to install and implement it? What can go wrong? What NOT to do (for the admins and the users)? Where to go when support people or architects need to look, change or troubleshoot? Etc.
  • Anything that is on the roadmap to be improved after the MVP-state. What does it do now? Into which direction will improvements most likely go? Where and how to make those changes? What to look out for? What will break and will need to be fixed when you make those improvements?
  • Anything that can be expected to need adjustments with organizational change. And trust me, organizational change will happen! The company’s name, the company’s logo, the businesses, there may even be splits, mergers or acquisitions on the horizon. So, make clear where your intranet logo and images live, what effect changing terms in the term store will do to your customizations, and where you need to make the necessary changes to make sure the organizational changes are reflected correctly.

This post was created after reading Gregory Zelfond’s recent post about implementing SharePoint in large organizations, which made me chuckle with recognition 🙂
Then Veronique Palmer commented with things you should document, so I thought I would give a real-life example.

Any other experiences or suggestions for documentation?

Developer image courtesy of lemonade at FreeDigitalPhotos.net

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s