Dear Microsoft: Site Designs for Good Information Architecture – Too Brittle?

Site Designs (See the Site design JSON schema article for all the great things we should be able to do with them) continue to seem like an awesome way to roll out a sound information architecture, yet they are still buggy and lack some basic reliability. I wish Microsoft would pay more attention to this capability and improve it as rapidly as they are improving other things.

As an example, I’m using a Site Design to instantiate a set of libraries with Content Types applied to each of them. Each library has one or more Content Types enabled on it, so we want the first column in the default view of each library to be the Content Type.

The first step was to create a prototypical site and build out the information architecture there. We tested that we could upload the documents we wanted with the right metadata. Once we felt we’d reach at least the 80/20 point, we used Get-SPOSiteScriptFromList to export the configuration for each library into the JSON representing its Site Script.

Since Get-SPOSiteScriptFromList exports some information that we don’t really need (out of the box columns like File Type and Shortcut URL, for example), we edit the exported JSON down into the required verbs and actions in order to layer our information architecture onto a new library. This culling is important to improve the efficiency of the Site Design – they can be quite slow to run, and unnecessary steps only make that worse. Plus, it can mean you’ll run into Site Design limits. (See SharePoint site design and site script overview for the current limits.)

As I mentioned, I’ve created a separate Site Script to instantiate each library. That way we can mix and match the Site Scripts into different Site Designs, as needed. Each Site Script in the Site Design looks something like this:

• Create a set of Site Columns (createSiteColumnXml)
• Create a base Content Type inheriting from Document with the Site Columns defined above (createContentType)
• Create multiple Content Types which inherit from the base Content Type (more instances of createContentType)
• Create a library (createSPList)
• Apply the Content Types to the library (addContentType)
• Delete the Document Content Type from the library (no cheating and adding documents with no metadata!) (removeContentType)
• Update the All Documents view to show the Content Type and the Site Columns (addSPView)

From there, we create a couple more sites using the Site Design. We’re bound to have missed a few things as we populate those sites, so we go through a lather, rinse, repeat process here.

For those of you who are tempted to say “Well, then you didn’t have your requirements nailed down clearly enough up front”, welcome to the real world. We’re in the age of iterative development. Waterfall ought to be dead.

With this approach, we want to be able to rely on the fact that Site Designs can be applied to any site multiple times. Being able to re-apply Site Designs as they evolve is a critical benefit of the Site Design idea and a key to maintaining an evolving information architecture. Information architecture must evolve with the organization as it, too, evolves.

Site scripts can be run again on the same site after provisioning. Site scripts are non-destructive, so when they run again, they ensure that the site matches the configuration in the script.

SharePoint site design and site script overview

This re-application idea relies on the programming concept of idempotence. Check out Bob German’s (@Bob1German) great post about idempotence: Idempotent Site Scripts for SharePoint)

What we’re doing here is such a common set of tasks. I’ve done things like this manually for more years than I can count. With Site Designs, there’s so much promise to roll out structures like this across many sites to ensure a consistent information architecture and update it as time goes by and the information architecture evolves.

Unfortunately, that promise isn’t yet fulfilled because there are a number of things that go wrong here:

• In order to keep my Content Types well-organized, I put them into groups, always named with a leading underscore (e.g., “_ClientName”) so they rise to the top of the lists in the management UIs. Site Designs don’t let you specify the group names, so everything ends up in the Custom Content Types group. This makes a big set of Content Types difficult to manage, and the hierarchical work I do to come up with a good information architecture is still there, but indiscernible in the Site Settings. (I organize my Site Columns the same way. Luckily, I can specify the group for them in the Site Design, and it “sticks”.)
• If a view already exists (like the All Documents view above), then any additional columns in the viewFields specified with addSPView are added to the right of the existing columns. This means addSPView really doesn’t have an idempotent option; I can’t add new columns to views so that they land in the right place. I can create a new view and everything lands correctly, but if I apply the same Site Design again, that view already exists, so…stuck again. This means I can’t use a Site Design to reliably create views, except the first time I run each of them.

Both Bob and Beau Cameron (@Beau__Cameron) are my go-to guys about Site Designs; we’ve commiserated about them way too many times together. Beau helped me figure out the details of what was going on here the other day.

We want to believe in Site Designs, but they are still just too brittle. Sure, we can generally get what we want done, but these sorts of business requirements for a good information architecture are too common not to work well, and easily.

I’d like to see a good road map for Site Designs as well as some information about how they fit into the overall idea of maintaining a strong information architecture, especially with the investments Microsoft is making in Project Cortex. We got a few hints at Ignite, but not enough to plan ahead. Are the shortcomings and lack of attention due to Site Designs just being a stop gap capability which will be replaced by something else later? Or are they truly the way forward, as we’d like to believe?

I so want to stay behind Site Designs as a valid and useful capability. Microsoft: help me understand that I should continue to do so, and stay on top of fixing bugs and improving this capability, along with communication about what is going on.