Developer Documentation: Sharepoint Document Management vs. ScrewTurn Wiki [closed]

Answer 1

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 2

A wiki is much more likely to be used than a bunch of word docs simply because it is quicker and easier to find an entry to edit or create a new page than a bunch of word docs will ever be!

The question then becomes which wiki

Almost any wiki is better than the SharePoint wiki, that one is beyond a joke

Screwturn is excellent, has ACLs and WYSIWYG in v3, and is very easy to extend

e.g. Using the XSLT plugin is great for embedding the output of server processes, CI builds, tests, source control stats etc

e.g. We have a OLEDB plugin that reads critical values out of various company databases and embeds them into pages describing what the data is and what values it should have. We have one master page that lists all the pages that have data outside of prescribed ranges. Sort of a blend of FIT and a systems monitoring tool

If you have a management possition on "everything" has to be in SharePoint, then there are Screwturn plugins that render out the Screwturn pages as PDF, HTML, xml etc (you can convert to docx then) and have a script to dump changed screwturn pages each night to SharePoint for searching and "management" purposes

Answer 3

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 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

Hey I've got experience here. We started to use ScrewTurn at work, but we were asked to switch since the company had already bought SharePoint. Documentation quality went down because Word documents are no match for a wiki, and as others have pointed out, SharePoint's is not up to par.

In my opinion, nothing beats a wiki for documentation. I think it's mainly the ability to create links to pages that don't yet exist. That way I can stub out documentation and the rest gets filled in as needed. It makes documentation more concise and readable.

With Word docs, hyperlinking is not very likely to be used, but it's so helpful to the readability of documentation. I could go on...

Answer 6

As a generalisation, word is pretty awful for technical documents. Because it works very poorly for large, structured documents it encourages a proliferation of small documents with no cross-referencing between documents. Scale this up to any significant size and you will have trouble finding which documents pertain to an issue you are trying to investigate. As time goes on you will find people wasting more and more time hunting through a jumble of word documents, spreadsheets, visio diagrams and even powerpoint presentaions to find information that may or may not be recorded.

Putting them into sharepoint just forces you to route your searching through a browser.

Any technical documentation tool must support cross-referencing between documents to avoid losing those references. A wiki achieves this far better than word ever will. Also, it is much easier to incorported generated content such as data dictionaries or API docs into a wiki, and you can make the XRef targets stable.