Documentation Migration Strategy

(Robert Down, BSN, RN) #1

Documentation is a sour-spot on our project. We’ll be moving to a new documentation platform over the next couple of months. Below is a migration strategy I’ve been working on. There are still a couple of areas I need to finish, but I wanted to post it so the community can offer any feedback.

I’ll warn you, the doc is a bit lengthy, so here’s the tl;dr:

MediaWiki is outdated and difficult to maintain. We should move to Drupal and restructure our documentation - split the docs up for “End User”, “Administrator”, and “Developer.” Documents would consist of “How-to”, “Guides”, and “Reference.” Documents are tagged with release numbers. One document, one topic.

(Robert Down, BSN, RN) #2

(Daniel Sandoval) #3

@robert.down I left some comments inline. It looks really good and I am excited about the direction we are going :slight_smile:

Focusing documents on specific audiences is a great idea so that users can know that they are reading the right level of documentation for their task.

According to NNGroup:

Even though it is better if the system can be used without documentation, it may be necessary to provide help and documentation. Any such information should be easy to search, focused on the user’s task, list concrete steps to be carried out, and not be too large.


The way you broke up documents into How-to, Guides and Reference seems to accomplish this goal. In the future, i hope that we can provide this documentation as a part of the user’s workflow. Similar to what intercom is trying to do with their knowledge base integration:

Documentation and Codebase
(Robert Down, BSN, RN) #4

Looking forward to the migration process, one immediate goal will be to drop mediawiki as quickly as possible. Unfortunately this may take some time as links fall away. I notice a lot of content which no longer really applies to our current system and I have no intention of migrating stale content to the new document types (How-to, Guides, References). Instead I think I’m going to make a special document type called “Archive” and everything that won’t be migrated can be dumped there.

As for the actual migration process itself, I’m planning on using a tool called Pandoc, basically a swiss-knife of document-markup transformation. I will dump the each page to a file (in mediawiki’s markup) and use pandoc to convert that to HTML and then import the HTML page into Drupal. It will be a semi-automatic process (The markup conversion will be automatic but I’m sure we’ll need to do some kind of cleanup after.

I am hoping to get up and running where we can test all of this. My guess is everything will get dumped to the Archive category and we migrate current content to the new documentation strategy.

(Robert Down, BSN, RN) #5

Just wanted to give an update. I know I’ve seemingly fallen off the face of the earth but this semester proved busier than any other in my program. Luckily I’m finished (And graduate with my Bachelor’s of Science in Nursing on Friday!) and hope to get this project back up and running full steam.

(Sandra Gutierrez) #6

Yay, Congratulantions!