Developer Documentation: Sharepoint Document Manag

Question

Background Info

I am working on setting up a method for my company's developers to share documentation and information about our various internal systems. This would range from information that would be useful for bringing a new employee up to speed, to descriptions of common problems users have with the systems and their resolutions.

This seemed like an ideal job for a wiki to me, and since our company only has the ability to host ASP.NET applications, I set about researching the available ASP.NET wikis. ScrewTurn Wiki seemed to be the most appropriate one, it's very full-featured and there are several plugins available that would be useful for my situation, including syntax highlighting and AD integration.

However, upon starting the process to have ScrewTurn deployed to our intranet, it was suddenly remembered that, hey, Sharepoint 2007 has a wiki, and since we already have Sharepoint set up, couldn't we just use that? I did a bit of evaluation of the Sharepoint "wiki" (in quotes because it barely qualifies), and was able to demonstrate that it wouldn't be suitable due to its many deficiencies, which I won't list here.

Now at this point, it's been suggested that perhaps I don't need a wiki at all, couldn't we just do everything in Word documents and use Sharepoint's document management functionality instead?

The actual question

So what I'm looking for is some additional ammunition, preferably from people with experience. What are examples of things that will be difficult or impossible with Sharepoint in the context of internal developer documentation? What is a wiki better at? Hey, I'm open-minded, what is Sharepoint better at?

What will make it worthwhile to deploy a wiki instead of simply using what we already have?

Answer 1

We are currently using a combination of both, sharepoint for specs and formalized docs and a Wiki for "tacit knowledge". Each of our solutions has a page in the wiki and this works very well due to the ease of adding content.

Answer 2

I'm hoping this is going to be some use - extra points or not :)

SharePoint Server (SPS) or Windows SharePoint Services (WSS) is VERY good if you are working with office documents - you can version, check in/out, share, search etc. I dont think there is anything on the market which comes close for that function (it also does custom lists and stuff really well).

But as you point out, the WIKI function is, well, sub-standard.

For developer documentation, a wiki is much better, as you can easily interlink documents, and even if for the sole reason that developers tend to LIKE the wiki markup! Makes it feel like they are writing code, not a document. Well, ok, I like it. Word documents? endless frustration, especially for code snippits and things like API's. Wikis' usually handle code and structured formatting really, really well.

But here's the main point of me posting:

If you can host ASP.NET - and if you have SPS you can already! - then just install BOTH OF THEM. Make a new IIS virtual host, put STW in that one ('cos SPS will be in it's own virtual host)*. Massage the DNS a bit (so you can hit http://wiki or something), and just go for it.

As it's all internal to your company, and STW has windows security and versions, security isn't a huge issue. Each page can be linked to from anywhere - it's an HTML page after all - so you can link to it from the SPS wiki if you really want to. There is some lock in, I guess, but not a lot.

Here at BBC Worldwide, we use a number of technologies:

• Atlassian Confluence (WIKI) for some projects. I love this wiki, but it IS a big enterprise-y system.
• Screw Turn for some intra-department stuff.
• Trac for some other stuff (someone else set it up with SVN on our source repo, so it's used a little - it's nice, I rather like it, but it's a a*se to setup)
• SPS/WSS for documentation management.

there are links between the STW, Trac and SPS - eg we try not to store docs as attachments in trac, rather link to them in SPS, etc.

Works well.

As for ammo: SPS works well if it fits what you want to do (or YOU can fit what IT does). If not, you are either screwed, or need to do a lot of dev, which is really the same thing :)

But aside from management getting all funny about it, I can't see a problem with installing both. STW is free after all. You have server(s).

And it gets dev's writing docs, which is seldom a bad thing. Ok, it's a bad thing if real humans have to read it, but docs for other dev's? All good.

*note: virtual HOST. Not virtual DIRECTORY.

Answer 3

Nobody could ever be happy with the SharePoint wiki by comparing it to any other wiki system.

So, don't compare it. It has the basic features necessary for a wiki to be useful: you can enter (somewhat) richly-formatted text, along with links to other pages, whether or not they exist. Clicking a link to a nonexistant page will take you to an edit page for the new, empty page, allowing you to save the page.

Yeah, the picture support sucks. You have to create the picture first, then paste the URL of the picture. So, take two minutes and create a picture library to post wiki pictures in.

Remember the main goals for a wiki - not to compete with other wiki tools, but to get ideas written down, quickly, and without stopping to structure them. Structure can be added later, if at all.

As others have said, telerik offers a replacement for the Rich Text editor, there is a CodePlex procject working (slowly) on improvements, and, people, it's SharePoint - if you don't like it, you can customize it. It's ASP.NET, web services and Windows Workflow Foundation.

I don't recommend anyone go out and buy a MOSS license just to implement a wiki (or blog, for that matter). But if you've already got the SharePoint infrastructure (perhaps as part of Visual Studio Team System Team Foundation Server), then go for it. I've seen several SharePoint wiki libraries used to hugely improve the amount and quality of developer documentation available to several groups within a large software development organization. Once we shut down discussion on how great other wikis were, quite a lot of documentation just happened, by itself, just like it's supposed to do.

Answer 4

I use Sharepoint quite regularly, and I find it kind of slow and all kinds of annoying. If everything is already an Office document AND if you're company is willing to keep everyone's computer up to speed with Office versions, then Sharepoint can work fine. If you've got a variety of Office versions (like we do) then it's far less good. My machine has some older versions of office components and the integration doesn't always work correctly. I've learned to not try to use integration at all.

The most important thing with either solution is to make sure your people know how to use it. We had some problems early on (versions of files with different names instead of using the versioning built into sharepoint) that were really just gaps in people's training.

Answer 5

Here is an open source extended wiki for SharePoint that may be more suitable:

http://www.codeplex.com/CKS/Wiki/View.aspx?title=Enhanced%20Wiki%20Edition&referringTitle=Home

Answer 6

First, check out this StackOverflow thread. A similar question was asked about Sharepoint wikis, and the answers there both pro and con are really useful and outline the "impossible in Sharepoint" part of your question.

I'm in the middle of trying to implement a team wiki in Sharepoint right now for almost he exact same thing as you, after having used Sharepoint for team documents for a couple years. My observations:

Sharepoint Document Libraries

My experience is that Sharepoint for documents is decent. It can be flaky and you'll sometimes lose edits or have performance issues, although a good Sharepoint support team can help with some of that. I did find the Sharepoint document libraries better than storing things on the network. It makes the docs and libraries easy to link to. Judicious use of the metadata properties can make a Sharepoint list view very useful for seeing what the document is, what it's for, and what status it is in, so our analysts, PMs, developers, etc., all know at a glance who has the ball and when something is waiting on them. That was started for a project a couple years ago; today Sharepoint 2007's workflows can probably provide notifications.

There's also version control for the documents. But as some others have noted doing things in documents has overhead and flaws involved in composing, downloading, and sharing. Check-outs of documents help, but loose cannon developers can download docs, edit them, and than store them elsewhere thus defeating the version control. This has happened to us, although that's a discipline issue and not Sharepoint's fault.

Sharepoint Wiki

Per the Chris Hynes answer, friction is a good word to describe the issue. For quick reference of a team's internal infrastructure details the wiki seems to work better for us. The wiki makes the data almost instantaneously visible, without having to click a link first and wait for Word to load. Edits are quicker and easier too...and although I'm still experimenting with it, the Sharepoint wikis have version control and allow "check outs" of wiki articles.

As you and the other SO thread pointed out, compared to other wiki engines, Sharepoint is lightweight. What is it better at? Well, I'm using it because it's there, didn't require any special setup, better than nothing, and frankly, it works fine for internal stuff that doesn't have to be robust or customer-facing. It's easy to sell to the boss because it doesn't cost anything more than what we've already spent. The wiki also can't as easily be compromised by the loose cannon types I mentioned earlier, and we'd be able to view the audit trail or rollback if necessary.

It's easy to add and cross-link entries, although if you want to embed graphics, you have to upload them first to a Sharepoint library. You can edit the HTML in the wiki too, although I'm not sure what limitations there are with that, and controlling the CSS I believe is not available without security access and Sharepoint Designer. So anything other than text (like tables) is not very robust.

So far I like it better than storing everything as documents. The immediacy of seeing and editing the data gives the wiki a real edge. It is certainly easier than pulling down a document and checking it back in. With the average documentation-averse developer, it helps to remove the barriers around keeping information updated.

Something else to consider. Do you expect your devs to be enthusiastic and actively involved in editing the wiki? If so, you might want the discussion features of a different wiki engine. My developers are like most; the two things they hate most are testing and documentation. So I'm the guy creating articles explaining the build procedure, the database environment usage, the application instances, server map, the SOX documentation checklist, etc. The other devs will mostly reference it and post minor updates. Our versioning and concurrency support aren't being heavily stressed.