Fear and Loathing - Archives - 2010

SharePoint Document Libraries and Horrors Oh My

Friday, August 27, 2010

SharePoint SharePoint 2010

16 Comments

I thought I would capture a few ideas around document libraries and share with the rest of the class. These are not “best practices” as I don’t want to sound too preachy so let’s call them “pretty good practices that you might want to consider if you have some time” (which is far too long for a blog title, hence the one I came up with is going to have to do).

SharePoint Fight Club

The first rule of SharePoint. I want you to repeat after me.

“SharePoint Document Libraries are not file shares.”

Good.

Now say it again.

Good.

Remember this, above all other things we’re going to talk about here, and you’ll be golden.

Document Libraries are not File Shares

I have to repeat this here because it is key. If your users are asking you to put a file share into SharePoint then you need to beat them upside the head when they talk about “replicating the folder structure” or “like for like” or “make it just like *that* (and points to file share)”.

If you really must make some kind of analogy and your audience knows something about databases (even Access), rather than saying document libraries are like file shares say “document libraries are like databases”. While SharePoint sits on top of a database it’s kind of irrelevant what the backing store is (side note, Dear Microsoft, please make a pluggable store for SharePoint in the next version) a list or document library is pretty much like a database. A document library may “look” like a file share just because it lists documents (which originated as files) and contains folders (assuming you left this feature on, more on that later) but it’s more like a database than a file share. Each document is just a blob associated with metadata (title, size, date, author, etc.).

A team once built a “document management system” in Oracle using… wait for it, blobs associated with tables with columns to hold the metadata for the blob. I laughed when they couldn’t store certain types of blobs and spent a ton of time trying to index the system and build a web UI on front of it (and yes, SharePoint was in the environment, that team chose to talk to me after they built it in isolation). True story.

Would you create a folder in a database? No. Great, let’s move on.

Working Online

Something that is going to be a big hurdle for your users (and yourself if you haven’t got into the mindset) is that you do not need to create new documents on your hard drive. Ever. I see this behavior all of the time:

Start Word/Excel/PowerPoint
Create content
Save file to “My Documents” or some such silly place
Start browser
Navigate to SharePoint site and document library
Click on Upload
Navigate to find document on local drive

Really. Drives. Me. Nuts.

With the Office integration with SharePoint 2007 or SharePoint 2010, you’re able to fully integrate your editing experience with SharePoint. If you know your document is going to go into SharePoint then either a) save it to SharePoint when you’re done or b) launch a New document from the document library (which in turn will open the client app and save back to the SharePoint library by default).

It’s really simple to show users but will take some coaxing to get them to do this. Of course not everything belongs in SharePoint but it drives this SharePoint guy batshit crazy when I see documents in My Documents, a USB drive, a network share *and* SharePoint (of course every location has a different version).

Start using the tools as Microsoft intended you to and you’ll be in a better place.

Do_x0020_not_x0020_use_x0020_spaces_x0020_in_x0020_names

When you first create a new document library please don’t name it “Project Documents” or “Expense Reports – March 2010” or “Famous kittens I would like to juggle”. Instead name it “ProjectDocuments” *then* go back and change the name in the library settings. The reason why is when you create a new document library and call it “Project Documents” it takes on an internal name of “Project_x0020_Documents” and accessing that library in the browser will result in a url of “Project%20Documents”. That’s fugly not to mention a PITA to deal with.

Make everyone happy by crunching the name then going back to rename it to something more human friendly. Frankly I wish SharePoint did this automatically (like it does for publishing pages) but until that happens, we should make a mental note to do it ourselves and be good SharePoint citizens.

Hint: This is my golden rule for lists, columns, and views too!

Don’t Get So Attached

The worst sin (well, one of many) is some guy sending me an email with a document attached to it, usually about a minute after I get the alert the document was added to the library. Better yet, the document copied to a dozen people on my team. I can see the need for this if you have external users who don’t have access to your SharePoint site so that’s perfectly acceptable but you should really compose an email to them with the attachment and send the link to your internal team (I know, two emails are better than one? Your internal team doesn’t need the attachment).

It’s really simple to get a link to the document. Right click, copy shortcut, paste. Another tip when pasting the url into an email is to write a word to describe the document (or even “Document is here” is fine too) and highlight the word or phrase and hit Ctrl+K to create a shortcut. SharePoint links can get somewhat long and ugly so pasting that directly into an email can break up the readability. It’s an extra keystroke but worth the effort IMHO.

Lather, Rinse, Repeat

If you do live in the world where you are interested in versioning is important then go over the draft/publish model with your users. Draft versions have two attributes. First they’re minor versions (0.1, 12.3, 8,348,23.58,328). They’re incremented each time you check a draft version in (and have major/minor versioning turned on). Second, they’re only visible to people that have edit capability on the document library.

For example you have some requirement document that’s going to evolve and perhaps go through a few public versions (say one version for each phase; architecture, design, construction, etc.). The team agrees to use versioning and you twist their arm into a using draft/publish model. It’s really simple. Every time they have a minor edit, they check it in (leaving it in draft). The team juggles around reading it, making comments, pontificating, whatever until they’re in agreement of the contents. Then the custodian of the document checks the last version in and chooses to publish it. It becomes the next major version up and visible to readers of the site.

This works well because all of your minor edits are behind the scenes (and the number of them can be limited if you choose) and people get to see the polished product. Then it’s back to draft modes and “dot” versions, the cycle repeats itself, until the next major change. Treat documents as living entities that grow up (like an application, or a kid but without the mess) and maybe apply Semantic Versioning to them (publishing a major version when there’s something useful to communicate rather than bumping up the major version on every check in). This will cut down on the chatter between the team and readers don’t have to keep asking what the big change from 1.0 to 2.0 was (remember to add comments when you check in a major version).

Document1-draft.doc

How many times have you seen a document named this in a document library? True, you might not have versioning turned on but c’mon people. Really? That’s like using zip files for version control when you have a perfectly good SCM system in-house. The best part is that you look in the doclib and see Document1-draft.doc, Document1-final.doc, Document1-final.docx, etc.

Sit down with your users and explain the virtues of versioning. Maybe it’s not for them and maybe they don’t need full blown major/minor, draft, publish versioning. That’s fine. However if they’re going to be working on documents that evolve and need to be reviewed it’s probably time to show them a draft/publish model.

Bottom line, if you see the –draft, –final behavior then nip it in the bud before it becomes a problem. You don’t have to call your user out in the daily stand up and berate them in front of the team, but be supportive and helpful. Not everyone is a SharePoint Guru like you (and for good reason).

SharePoint Inception

There are some people that have done some nice things with folders (Laura aka “@wonderlaura” Rogers has a great article on Per Location Views). I feel these are exceptions to the rule. Systemically it probably stems from the file share stigma. People organize information using folders so it’s natural to them. The problem is that (remember?) document libraries are *not* file shares. Stop treating them like that.

Folders are like IFRAMEs. They were a great idea but as time went on, without people knowing any better or good ways to use them, they became ugly and nowadays IFRAMEs are pretty evil and frustrating and we don’t have a lot of them around. We’ve grown past them. Now let’s move on from folders.

A few things about folders that make them different from nuclear reactors:

Document libraries have a path limitation (actually I think the limitation is on IE or maybe even HTTP) so nesting lots of folders inside of folders chews this up real quick. Trust me when you exceed the path. The error message you sometimes get is a blank screen.
You generally have to know where something lives in order to find it. This can lead to dozens of clicks on folders depending on how great your folders are named.
Folders are neither discoverable (other than the top level ones) nor searchable. Metadata is.

Folders don’t help organize information. Yes, I create a folder named “Expense Reports” but that doesn’t mean my smart users are going to put expense reports in them. Or a folder named “Architecture”. I guess I’m going to expect Visio drawings or stickmen or something in here but what happens when I start seeing server inventories in spreadsheets. Is it architecture or detailed design (or a document misfiled from some other project). Metadata and Content Types help you organize information.

Folders attach a fixed path to a document. If you drop something in a folder that’s how you retrieve it. If you decide one day to simply move it up or down the folder hierarchy, guess what? All those links are now broken. Using metadata to organize information means “I don’t care where this is but I know what it’s about”. Get into the habit sooner rather than later.

Where Am I?

Just a bit of a follow-up to using folders. One of the worst things you can do is drop a document library onto the home page of a site. Your site is for information. Try putting announcements, tasks, or pictures of kittens on your team/project home page. Not documents.

If you put a document library on the home page and have folders-from-hell enabled have you noticed the evil that is unleashed? No. Take a look again. Click on a folder. Now another one. Now another. Keep going until you’ve descended into the 9th level of Hell. Now take a good look at that url in your address bar. Go ahead. Click it. Now send it to someone with a note “I left your termination notice here” and paste in the link. When your unsuspecting suspect clicks on said link, nine times out of ten, he or she will be taken to… THE HOME PAGE of your site. Cool beans. Note that I said “maybe” so it’s not a guarantee but it’s also not very pretty. Like any Jessica Simpson movie pretty. And your users will grumble and gripe and blame SharePoint, not Jessica Simpson.

The other pro (or con depending on how full or empty your glass is) you get from dropping that beloved document library on your home page is the all important bread crumb trail. Pro or con, the breadcrumb trail that you see above a document library when you’re navigating through it is gone. It only exists when you send your users to the doclib itself so forget any navigation up the levels of Hell (or even knowing where you are if you care).

Metadata, metadata, metadata

Oh but Bil, I can’t find my documents without putting them in a folder called “My Documents”. Now after you noodle on that statement for a minute think about it. You unleash the fury of SharePoint on your team spouting commandments like “THOU SHALT PUT DOCUMENTS INTO THY DOCUMENT LIBRARY” and your team has no clue how to organize documents in a document library (let alone their own desktop) and you yell at them for not “categorizing” or “classifying” them properly.

Give yer head a shake.

You can’t bash people for playing the game incorrectly if you don’t give them the rules to the game.

Metadata is king in the SharePoint world. If you need to organize your documents dump them into a doclib and stick a column on said doclib called “Category” (or “LOLCATegory” if that turns your crank). Make it a choice field and let users add their own or make it a lookup into a list (or better yet use the metadata feature in 2010 but if you’re on 2007 we live in simpler times). Then create a view grouped by category. Create some searches on the category column. Create some views for categories the team feels important like “Important Architecture Documents” or “Things I would like to do to Bil if I could”. Pretty soon the team will be happy because they don’t have to spend 3 hours looking for a document that’s in front of their face.

Note that the space-in-names rule doesn’t apply to choices in a choice field. It doesn’t form a url and SharePoint doesn’t go tossing in its “_x0020_” macro on you. Be wild.

Breaking Boundaries

One final question about document libraries is how much is enough? How many document libraries do I need to store my documents. The answer my friend is “it depends” (oh you knew I was going to say that). Only you or your team or the collective wisdom of whomever is using the library knows what the right division is.

There are a few factors you can use to decide where to draw the line. Size might matter (although less so in SharePoint 2010). You might want to break up document libraries based on security. While you can apply security to (gasp) folders or items in SharePoint, it might make more sense to just seclude off a library for privacy. Remember when you created the first team site and got a “Shared Documents” library for free? There’s nothing but fear and common sense preventing you from creating a “Team Documents” and only allow members of the team to have read access (“Unshared Documents” just sounds a little badly in the grammar department).

I can tell you I don’t know what the right division of document libraries is but I can tell you what the wrong one is. One document library per document. Yeah, I’ve seen it. It’s evil.

Christmas Time

Okay, to wrap up let’s just remember two key things: