A wiki website is a great solution when you need to maintain a lot of information that is likely to change, and requires input from multiple people. They are a natural fit for maintaining product documentation for software projects. My team used to maintain support information for our applications in Word documents in a version control tool. The documents were structured using an "enterprise standard" CMM-inspired template. There were specific, numbered sections for each type of information, and a whole lot of standard template text explaining the purpose of each section. There was too much friction involved in finding and updating information in the documents, so neither happened very often. It wasn't long before the documents were completely irrelevant and unused.
I decided to install FlexWiki, and created a site for my team to use. We each did a brain dump and soon had all of the needed support information available. The information was easy to access, and equally important, easy to update. There were some quirks to using the wiki (YourProseStartsToLookALittleUnnatural), but there is no doubt it was a vast improvement over the templated Word documents.
Then Microsoft OneNote 2007 was released, sporting a new "shared notebook" feature. With OneNote, you get the same ease of access and ease of editing that a wiki provides, but with a much smoother experience. To mirror the history log functionality of a wiki, you can store your shared notebook in a versioned SharePoint document library. The only disadvantage of OneNote compared to a wiki is the requirement for all of your users to have OneNote. If that requirement is already met, I believe OneNote is a far superior experience. OneNote advantages at a glance:
- Easier editing. Toolbar buttons and shortcut keys instead of funky markup syntax to learn. No need to switch to "edit mode".
- Richer formatting. Text can be many styles, sizes, colors. Screenshots and other images can be easily pasted inline. Documents and audio clips can be attached to a page.
- Easier searching. Searches find words in any page text, image, or audio clip!
- Offline access. All data is synchronized to your local machine when you are connected to the network, so you can access it when you are disconnected. Any edits you (or others) make are automatically synchronized to and from the shared location when you reconnect.
My team was sold on the benefits, but we had a sizable investment in our existing FlexWiki installation. Thankfully, OneNote has a nice API that makes it easy to get data in and out. I was able to put together an application that migrated our entire wiki to a OneNote notebook, with all formatting and hyperlinks intact.
I originally had visions of making a robust migration tool. My plan was to create a class derived from FlexWiki.Formatting.WikiOutput that would render OneNote XML. I would then be able to take advantage of FlexWiki's own parser instead of figuring out all the syntax myself. Unfortunately, it is not as easy as I hoped to get an instance of the parser running (it has a LOT of external dependencies). There were some promising mock classes in the UnitTest project that would have helped, but they were marked internal (grrr), and so out of my reach. I had already spent way too much time on a tangent creating OneNote DevPal to help me with this effort, so I settled for a brute force approach that could just enough markup for my specific site.
I am making the source code available in the hopes that someone can take it and run with it. Be warned, it is not pretty. It currently only supports the following subset of FlexWiki formatting:
- Intra-site wiki page links and external hyperlinks. Federated wiki links are not supported.
- Bold and italic text
- All headings are simply translated as bold text
- Bulleted lists (but not nested bulleted lists)
- Tables
Command-line syntax:
wiki2one <wikiRoot> [Notebook] [SectionName]
wikiRoot is the full path to the directory containing your *.wiki files. This is the only required parameter.
Notebook can be either just a name or a full path to a Notebook folder. If the notebook does not exist, it will be created. If a path is not provided, it will be created in the same location as your first existing notebook. If a value is not specified, the default is Wiki2One.
SectionName is the name of the OneNote section that will contain the migrated pages. If it does not exist, it will be created. If not specified, a default is generated based on the current time.
Note that all pages are imported into a single OneNote section. It is very easy (and highly recommended) to then organize the pages into logical sections once the migration is complete.
If you make improvements to the code, let me know, and I'd be happy to host it, or link to it from this post.
Download the source code
Download the executable (requires the .NET Framework 2.0 runtime)