Introduction
Several tools exist for making wiki pages but they all seem to me to be more involved than this method based on using LibreOffice’s Mediawiki export capability. I like LO because it’s a very well known industry- standard word processor, it’s free and composition with it is quick and easy.
I use Linux so all the apps I discuss are for that OS. I do know MS Windows does have a LO edition, and some comparable utilities (but NEVER use notepad!) though I’m not familiar with them. And I hear MS Word does have some sort of mediawiki addon, but again, I haven’t used it. However, I imagine that with proper preparation this workflow would work in MS Word also. Otherwise your wiki composition options require a commitment to learn large integrated word processing platforms or sending your content onto the internet. About which I know nothing.
Pass 1
For consistency I like to use the OpenEMR public demos (https://www.open -emr.org/wiki/index.php/Development_7.0.1_Demo) for my screenshots.
From a writer’s point of view I prefer to start with a text editor to compose the document content and make notes as I run through the workflow a couple times to get it right, taking large area screenshots of the features I want to show. I create meaningful names for the images and place the names where the images will appear in the text (for example, the pic:wikiformattingbar in the sample image below). Then once the basic doc has been composed, open it in LO Write and save it as a .odt. But I imagine that if you are good at on-the-fly composition you could just open LibreOffice Write and go for it.
Sample of my preliminary notes in txt format:
Pass 2
When finished with the content go back in the .odt file and be sure it’s formatted as you want.
• Crop the images down to the meaningful parts but keep them large enough you can see the location in the screen of the thing you are showing. Insert them where they go in the .odt
• If you do not use the formatting controls in Write the mediawiki export will not tag them properly
• Add bullet points
• Add bold and italics fonts where needed
• Set the headings of the hierarchical sections, heading 1, heading 2 etc
• Mediawiki’s numbering tag (hash sign #) does not work across blocks of other formatting so I just manually number any series of steps
Pass 3
• Export from LibreOffice as a mediawiki text file (‘File/ Export/ MediaWiki (.txt)’ ) and open in a text editor (LO will not work for this)
• Delete the title line (see caveats below)
• Move the image names into the Image tags
• Check for bullet point asterisks that didn’t get put on their own line
( looks like: ‘blah blah text* bullet text’ )
• I’m sure I’ve missed a few things here…
Publish Page To Wiki Site
Log into wiki site
• Click the ‘[edit]’ link in the section where the doc will go; put it in the User Manual/ User Guide of all the versions of OpenEMR that it applies to.
• Create the link (look at the others to design yours)
• Scroll to bottom of edit screen, click ‘Show Preview’, edit link as needed, click ‘Save Changes’
• Click the red page name to open the empty page
• Copy your mediawiki text to the text area, enter descriptive note and save the new page.
• Upload the images at the link at the bottom (pic of link)
• Preview → edit → preview → edit until everything is right.
• Add ‘new page’ explanation when done and click ‘Save Changes’
Caveats and Gotchas!
• Image file names: the mediawiki site contains all images in one place. So you need to make their names unique, hopefully relevant to the name of the doc so they won’t get confused with other images of the same name. Long names are good!
• Crop the image to remove distracting acreage, and resize to 600px max width.
• The name you give your page in the link will be displayed as the title of the page.
• OpenEMR’s wiki image upload page will automatically capitalize the images’ name so either UN-calitalize the name when you upload each image or capitalize it in the markup’s Image tags.
• The h1/h2/h3 headings turn into the Table of Contents at the head of the wiki page, indented to the level of the heading value.
• Much visually helpful formatting can be created with image alignment left/ right/ center or wrapping text around it. But it does get tricky to fine tune the wiki markup to display properly.
• One thing I am often guilty of: native English speakers (writers) should remember that contractions and idioms are not meaningful to most non- English speakers.
• One handy thing about using LO is, if you want to export the tutorial as a printable pdf, you’re one step away when the doc is finished.
Conclusion
Myself, I often think it’s useful to list other references for the topic I’m writing about-- helpful forum posts, links to wiki pages about related features etc. I find the Conclusion is a good place to put them, but that may just be my obsessive tendencies.
• See here for some good tips about mediawiki markup: Project:Help - MediaWiki
• Depending on the installed version the hints and tricks in that Help can be more or less useful