For the Children

imageLast Tuesday, in a post on my AIIM blog, I described my effort to begin crafting an Information Policy that will apply to one of our most recent SharePoint solutions. Eventually, I hope to have a collection of these policies bundled into a comprehensive information policy for our company. That may not happen in the 5 to 7 years that remain before I retire, but I’ve heard that it’s good to have goals. This first attempt was presented to the department earlier this week and the draft was well received, even after I explained that most of the work that remains will fall to them. We moved onto the other agenda items, but we kept coming back to the information policy, and I began to realize just how important this document is going to be. The point where this became most clear was well into the meeting when one person asked

“…how is this [SharePoint site] really any different than the K: drive?

It’s not the first time we’ve been asked this question in the years that we have been trying to move our content from shared folders to SharePoint, but this was perhaps the easiest it has ever been to answer that question.

“It’s different because we can answer three questions for every document on this site that we can’t usually answer for content on the K: drive:

1) Why did we create this document?

2) Who was involved in its creation and disposition?

3) Why did we keep it?”

The inability to answer those three questions is why most of the content on the K: drive will end up staying there. Once the shared drives become read-only; it will take a lot of effort to explore the content and answer those questions. That task will get even harder when the people who were here as those documents were created retire. The loss of tacit knowledge has already begun to affect our ability to classify older documents, without reading them and without a little guess work, and it’s only going to get worse.

One of the tasks that this group has to accomplish is to move a lot of historic content into the site we created for them. This effort will be guided by the information policy, and the experience will help them refine the policy. A good example of how this will work came as we demonstrated Boost Solutions’ Classifier product for them. I’ve written about this product before, but in a nutshell, it lets you quickly tag and process a lot of content that has similar qualities. We stumbled upon two documents that looked like good candidates, a draft contract from a vendor and a list of changes that our staff had proposed. Before we could process these, the head of the department asserted that “we should not keep these, because, in this case we only care about the final contract” which we also had. This led to a short discussion of the kinds of documents where we want to keep drafts and review commentary and the kinds of documents where we don’t. This distinction mapped well to the library structure we had created and there was a placeholder section in the draft information policy for that kind of management decision to be documented.

Other elements of the policy are equally important for helping future employees answer those three questions. For example, there is a section titled Definitions. In the draft of that section, I included the words, library names and metadata elements that need to be clearly defined. Two library names that I included were Internal Communication and External Communication – why do we need to define these? Well, maybe we could live with one definition, but are we talking about external to the company or external to this function? Another definition was a word we have all seen too many times in business, “stakeholders” – when does someone we do business with become a stakeholder? That’s important because it’s a metadata term used in a lot of places, and if stakeholders are involved, the apparent importance of the document increases.

In our board meetings at the New England Chapter of AIIM, we often describe a documentation task as being necessary “for the children.” In other words, we are taking the time to document something that we figured out, but that future board members shouldn’t have to. That’s the difference between managed content and a bunch of files in a shared folder. That’s why you create information policies and that’s why you pay attention to the definitions, guidelines and clear instructions that people include in that very important document. Of course, the policies can change, so when they do, the document should be revised.

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.

A Case for Logging

clip_image002I have been writing off and on about a report processing automation project we are working on for our engineers. As far as report production goes, this is a pretty complex task. These reports go through a healthy review cycle and then they have an afterlife where they feed separate analysis and review processes for years to come. One of the features we added to this process this past week is a Log List.

You might ask “do you really need to log this activity?” – I mean a workflow controlled process is pretty easy to review. The process is driven by a status field, a task list and it feeds a few libraries; surely a quick look in those places will tell you what is going on with any particular document. True, but why make someone look in all those places when we can let them look in one place and see everything? Are we recording duplicate information in this log? Yes! Is this log necessary for control or auditing purposes? No! Did the users ask for this feature? No! The users did not ask for this feature, but I am betting that when we review this with the department manager next week, he is going to say “I like that”.

Logging is a function that we have been making greater use of recent years. It used to be that you logged transactions; period. That was because you needed to log transactions and logging was somehow expensive. Log files take up space. If you don’t think that is a serious concern, ask your Systems Administrator about log files. Logging activity requires extra code. A log database or list has to be built, information has to be gathered and somewhere, a line of code is added every time a log entry needs to be made. Logs need to be explained. Depending on the function being logged, the log files range from self-explanatory to cryptic. At the far extreme, we have Microsoft, whose system logs have spawned an industry that builds log analyzers and log reporting applications. At the opposite extreme though, is the workflow log that simply says “workflow complete”. Our target is somewhere in between, something with enough detail to chart the progress in layman’s terms, but not something that requires the completion of a course in log reading.

What about Dashboards? That question came up in our internal discussion, and we decided that there is an important difference between dashboards and logs. Dashboards are snapshots, a delightful view of critical information that you can quickly check and get happy or become concerned with something you are responsible for. Logs are more historical and more detailed in nature; logs are meant to support a more thoughtful review.

What about Auditing? When something needs to have an audit trail, it’s because somebody want to see that audit trail. They want to know specific things, but I don’t think an audit trail needs to support a thoughtful review. Audit trails are more like a Watchman’s Clock, they record activity for compliance sake. A useful process log is just that, useful. It contains the information that charts the progress of a process, points to where something went off the rails, and tells you about activity between milestones. That last point is important. If we simply look at document status or the activity of a workflow that is driven by document status, we will notice when the status changes. In our log, we also track when the document is saved but the status wasn’t changed. This indicates two things. First, our workflow is working, and second, that the document owner is still working too. No one needs to wonder if the owner just forgot about this document or is ignoring this task. That’s a simple example, but it’s the kind of information that is useful in an environment where people travel and there is no opportunity to simply visit someone’s cubicle and ask “how are things going with the … report?

We introduced this type of log in a transaction processing system over a year ago, and it has captured some interesting results. One pattern of activity we see tells me that they system doesn’t work well enough in support of the user. Too many attempted (or perhaps test) transactions are being performed. As I discuss this with the user, I hope to make this system better. I’m not sure what the process log in SharePoint will tell me, but if it helps us improve the process down the line, it will have been worth our time. If it proves to be useless, we can always delete it.

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!