Wikify Your LibreHealthEHR Docs
This is a companion document to the 'LibreHealth Documentation Style Guide'. Once you compose your document to the final draft version you will then need to prepare it for publication to the LibreHealth EHR User Documentation wiki site. Just for fun, let's call it 'WIKI-fying your document'!
Many different tools may be used to accomplish this and you may investigate them here if you wish:
However, in this tutorial I will describe the use of the LibreOffice Write application which is a Free/ Open Source tool that works the same under Windows as under Linux. It may be less capable than some of the other tools but it is very simple to use and completely adequate to our needs here.
Please note that mediawiki does change some conventions and standards from time to time. Be alert for the markup not working as documented and check the mediawiki docs at https://www.mediawiki.org/wiki/Help:Formatting
- Harley Tuck, LHEHR Lead User Documentarian, 2 May 2019
- Be sure your images have a maximum dimension of no more than 600px. That is a good width to fit across a printed page, and should give plenty of resolution to zoom in on some part of the image. Minimum dimension should be no less than 100px, and the content must be adequately visible!
- It is possible to resize image dimensions in the mediawiki 'Image' tag but please do not use that since it encourages the use of larger images. Large images slow down the readers' page load times and take up more room in the wiki cloud.
- The mediawiki system stores all images uploaded to it from different wikipedia sites. Be sure your image names are unique to your document! See the requirements doc for naming convention suggestions.
- Depending on the version and variant of your LibreOffice (for example, it may be Oracle's version, 'OpenOffice') and the operating system you use (in some cases MS Windows required these) you may need to install plugins before your word processor will export to mediawiki.
- Have your LHEHR wiki account login at hand
- Create your document in .odt format.
- Preview the document to ensure that the headings are properly formatted in the appropriate heading levels, (H1, H2, H3) rather than being a resized and bolded font.
1. Open the .odt document in your word processor.2. On Main menu select 'File / Export'
3. Select from 'All Formats' dropdown at bottom right, 'MediaWiki (.txt)'
- It will export the text file to the same directory where the .odt file is at that moment.
Edit mediawiki .txt file
While it is not strictly necessary to perform these steps in this order, it might prevent the need to go back and re-do some steps.
1. The Title - Not all mediawiki markup is supported on all wiki installations. For example, the LHEHR wiki is configured to make the wiki page name from the link to the new page, then display that name as the page title. So delete the very first line of your mediawiki txt file which contains the title.
In the example below we see the link showing the page's name for the User Guide.
NOTE: in this multilingual documentation repository we specify the language of the doc using the standard language codes. For example, (EN-US)
Then we can see (oval, below right) that the new page has the title as given in the link, and the URL is the same, with spaces replaced by underscores.
Which shows why we need to remove the Title from the markup of the new page because it will be provided by the page display.
2. Numbering - Mediawiki provides automated numbering of lists. This only works with a continuous list. If the numbering is interrupted by a bulleted list, it breaks the auto- numbering. In that case you must number the list manually. Since manual numbering has a different appearance on the screen than automatic numbering it is frequently the best idea to simply manually number the entire document.
3. Images - The image name must be inserted into the image tag.
Locate in your collection of images the name of the image that goes in the text and insert its name in the tag.
Note that you can center or right or left justify the image very easily in the Image tag:
'[[Image:Image1.png|Center]] ' or '-.png|center]]' or '-.png|Left]]'
TIP: I have found it convenient to put the image file name next to the image when I insert it as I am building the .odt document. That way when the file is exported to mediawiki format the file name is right there next to its image tag (see rectangle and first oval in previous image).
The file name may be simply cut and then pasted into the image tag.
Upload to LHEHR wiki
1. Log into the wiki with the login you obtained from an LHEHR Administrator
2. Upload image files
a. In link list to left click 'Upload file'
b. In upload panel, click 'browse' to locate image on your computer
c. Click 'Upload file' button at lower left.
3. Create link to new page
a. Locate the page FROM WHICH the reader will access your new page.
b. Click 'Edit Source' of the section the link will go in
in real life, do NOT put your docs here!
c. In the text area at the bottom of the screen add the link to your page:
* [[Wikify_Your_LibreHealthEHRDocs| Wikify Your LibreHealthEHRDocs]] (EN-US)
d. Click 'Show Preview' at bottom of screen to be sure it's right (preview is in next image)
e. Save changes (blue button above)
NOTE: on the more public wikis it's important to tag the changes in the Summary box, and whether it's a minor edit. No need to do that here.
Upload mediawiki file
a. Click the new red link...
... to open new page
b. Open the doc's mediawiki .txt file in a text editor on your local computer
c. Copy/ paste entire contents into text area
Final Edit In Wiki
a. Scroll through preview looking for corrections.
b. Make corrections and re-check preview as needed
E.g., may need to adjust spacing between images and text, or between paragraphs, or change image alignments, or find some renumbering that was missed.
c. Finally: save page, that blue button at bottom left of the screen.
WIKI-fying your LHEHR documents can get tedious if you have many images, but in our (my) opinion that is the main drawback of using LibreOffice Write. Of the options available we believe this is the simplest and most accessible method to produce user documentation at this level of technical writing sophistication. LibreOffice is well within the capabilities of contributors who do not have IT/ Developer backgrounds or do not wish to become professional Technical Writers, to use the high- efficiency tools available in those fields. LibreOffice can deliver professional- looking results with minimal investment in learning new systems and applications.