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)

Introducing OneNote DevPal

OneNote DevPal is an add-in for Microsoft OneNote 2007 targeted at developers interested in OneNote extensibility. My goal was twofold: provide a source code example of how to create a OneNote add-in for developers just starting out, and then provide the tool itself that will aid in any OneNote integration development.

The add-in was created by following the very helpful guide provided by Dan Escapa. I would advise anyone just starting out to read that first.

The add-in itself is an equivalent to the "view source" function of a web browser. It allows you to inspect the XML that corresponds with the page you are currently viewing in OneNote. After installing the add-in, you will have a "DevPal" button on your OneNote toolbar. When you click the button, the OneNote DevPal window will open and display useful information related to the current page. If you navigate to a different page in OneNote, DevPal will automatically update to reflect the current page (after a slight delay). If you are integrating with OneNote and don't know their XML schema off the top of your head, you will quickly realize how helpful this tool is. For example, if you want to know how a bulleted list in OneNote is represented in XML, just create a bulleted list in a OneNote page, and then click the DevPal button to view the XML source.

Alternately, you can view the XML representation of your OneNote hierarchy. This is very useful if you want to programmatically add new pages, sections or notebooks using the UpdateHierarchy API method.

Features

• Display the contents of the current page, in XML form. Changing the page in OneNote will auto-update the XML in DevPal. It does not yet auto-refresh the current page if you make changes in OneNote, but you can get the same effect by navigating away, and then back to your original page.
• Display the current hierarchy in XML form. Changing the current page in OneNote will auto-scroll the hierarchy XML so that the current node is displayed at the top.
• Both XML displays are syntax highlighted specifically for OneNote XML (OneNote start tags, "ID" and "name" attributes, and CDATA text are emphasized)
• Displays the level, name, and object ID for the current page, and each of its parent containers, all the way up (Page, Section, SectionGroup, Notebook)
• Records all events raised by OneNote to the standard debug output. By running a tool like DebugView while using OneNote with DevPal, you can better understand what and when events get raised by the add-in API.

Download

• OneNoteDevPal installer
• Source code

Other Links

If you are doing any OneNote integration, the following links will be helpful:

• Dan Escapa's blog
• What's New for Developers in OneNote 2007 (part 1 - part 2)