Too Many Tools?

clip_image002My first woodworking project involved cutting a beveled edge on a block of wood with a hand plane. I learned how to layout the bevels with a marking gauge, and how to cut the bevel. Later, I learned how to cut that same bevel on a jointer. Later still, I learned how to cut the bevel with a router. Today, if I have a lot of wood to bevel, I use a router. If I have a small piece to put a bevel on, I actually prefer the block plane shown at the right. It’s nice to have options, but sometimes it’s nice to have a simple solution that always works. Stepping out of the workshop and into my day job, I often find myself in the same situation.

One of the frequently asked questions we get from our end-users is whether one way of doing something in SharePoint is better than another. In fact, one of the complaints we hear from people who have to train new employees, is that “there are too many options in SharePoint.” I don’t like to limit the way people interact with SharePoint, but having more options is not always a good thing. There is a reason that my father started me out with a hand plane.

A simple area of confusion, especially to a new SharePoint user is viewing and adding content. We try to create the default view of libraries and lists with the truly useful information visible and organized in an intuitive order. Then we create the view we use if we are going to put the library / list in a web part. Then (sometimes) we build or edit the Datasheet view. Of course, all of these can be sorted and filtered and we can create custom views for specific situations. If users want to add items, they can use the link at the bottom of the view, the new item row in the datasheet, and, of course, the controls on the Ribbon. We have one application where none of the people involved ever see the list or add new items in the same way. That’s a good thing (customize, personalize, etc.), but it can become a problem when one of those people is introducing the list to a new employee. We try to remind people that they can switch views and that they (or we) can create new views as needed. However, people often forget that SharePoint is this grand mutable platform, because they are focused on a specific solution that they use every day. In other words, they begin to think of the SharePoint they see as the SharePoint that is.

Earlier this week, we had a pre-launch meeting with some of the senior members of our engineering department, and the head of administrative support for engineering. The purpose of the meeting was to show them what we were going to show the entire department during a training session later in the week. We discussed some of the optional ways of getting from A to B, trying to find the one(s) we were going to include in the demo. When I was asked: “how many different ways do we want to show?” I suggested zero, and the head of the department agreed.

We decided to train people using the most common and most reliable method for each activity. We told them that there are options, sooo many options, but we did not show them those options during the training session. I wanted to avoid people having to hold mental bookmarks in place during the session. Once the solution is running, and everyone has gone through the training, hand-holding, solo-flight and a night-landing, then we can start introducing options. For some of the experienced users, SharePoint has already started working its magic; they have transferred their experience from other sites to this site, and that is very good to see. For the users who are new to SharePoint, there is currently only one way to cut a bevel.

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!

Timeless Lessons – Part II

Following up on my previous post, I want to share an example of how woodworking has helped make me a better SharePoint practitioner? Take a look at the table to the right; nice legs, wouldn’t you agree?

Making those legs was a complex process requiring patterns, jigs, tools, and some skill. Patterns probably make you think about templates and, if you have ever used a jig, you will equate jigs to workflows. Today, in the interest of space, I’m going to focus on tools.

As a woodworker, I never underestimate the value of tools – as a SharePoint practitioner, I sometimes do. I look at the requirements of a site and I am drawn to “I can build that with (substitute favorite technique here) ”. But, I’m reminded that I’m being paid to complete the site, not so much to enjoy doing it. When you consider the time it takes to build, test, document, deploy and maintain hand-crafted solutions, you might see newfound value in tools. The tool on the right is a Pattern Maker’s rasp which has a random tooth pattern that makes it easier to control and produce smoother results. When I started making the legs for that table, I didn’t own a Pattern Maker’s rasp and, compared to the rasps I did own, this one was expensive. But without that tool, you can forget about making those legs.

Buying tools vs. building your own tools vs. hand-crafting solutions without tools is a complicated decision. Once you know the total cost to buy a tool, compare it to the cost to complete your project without the tool (number of hours * your rate per hour), then, in the spirit of the AIIM blog series, ask yourself these eight questions:
  1. Can I meet the requirements without that tool?
  2. Can I reuse what I build in a different site with the same requirements?
  3. Does the tool offer other features that would help meet other requirements?
  4. Will my solution be as easy to deploy?
  5. Will I be able to alter my solution as requirements change? As SharePoint changes?
  6. Will my solution be easy to use or will it require my time each time it’s deployed?
  7. Am I planning to document my solution? If not, will my solution be of any use if I’m not here to maintain it?
  8. Is the cumulative weight of all my hand-crafted solutions sustainable i.e. can I maintain them all?
Building solutions is rewarding and often results in a “perfect fit” solution. Along the way, you can sometimes save your company money. On the other hand, adding tools to your collective toolbox can improve the broader SharePoint experience. A balanced approach is required if the goal is a robust and sustainable SharePoint installation.