Documentation Migration Strategy

Management and Administration Documentation
#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.

3 Likes
Non tech savvy - Non US use of Openemr is … - Question/Opinion
#2
#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.

See: https://www.nngroup.com/articles/ten-usability-heuristics/

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:
https://marketing.intercomassets.com/assets/messenger/videos/self-service-953d4ba9add4dd76988540ada283820daae78a078b832f061f6633f1f9f479c3.mp4#t=1

1 Like
Documentation and Codebase
#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 beta.openemr.io 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.

1 Like
#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.

2 Likes
#6

Yay, Congratulantions!

1 Like
#7

Hi @robert.down ‘Back in the day’ I did a bunch of documentation in the original mediawiki site and you’re right, a lot of that content is so old they don’t apply. But also problematic is that a very large number of docs written for the 4.x versions still do apply, mostly. It’s just that their functions have been upgraded by one or 2 new hacks which were never documented.

I’m curious, if a person were to start updating some of those docs (or, for that matter, writing completely new docs) what would be the best way to do it? Revise/ publish on the mediawiki site so when your migration gets up to speed they’ll get moved over to the new drupal site?

#8

Hi @htuck sorry for the delayed response. If you’re interested I can bring you in to the Beta site, which I expect we begin testing this week. I’ll reach to you with details

#9

Hi Robert-
I see I neglected to reply with my interest to be added to the Beta site. Would you please do that Thang for me?
How’s the testing going? Does this mean that new documentation written in the next few weeks should go on the beta site? Or just put them in the old wiki to be migrated when the whole site is moved over?
Thanks- Harley