I've mentioned this plugin elsewhere on this blog, however I feel that it deserves a complete blog post of it's own as it relates to the work I'm doing updating the Jomres documentation in 2022.

First things first : Do not install this plugin if your hosting service is running less than PHP8. I generally try to ensure that Jomres will run on older versions of PHP wherever possible, however this plugin uses a library that demands PHP8. That's why this plugin will remain a plugin, and not be made a part of Jomres Core.

The Plugin Information Plugin is a new Jomres plugin recently added that shows information about currently installed Jomres plugins.

TLDR;

 

 A screenshot, cos people love screenshots :

Software that is being actively maintained isn't static. Functionality and features change over time. Old, unused functionality eventually gets removed and new functionality gets added. Documentation needs to reflect these new changes.

Over the years I've used several different methods to document Jomres for it's users. Until now the most recent iteration of that, running for about the last 10 years, has been the manual at jomres.net/manual.

This has worked well enough. Whenever a new question crops up in tickets, if it gets asked often enough I've been prompted to add a new page to the manual. This helps to lighten the support load, but it creates it's own set of problems. Perhaps the cause of those tickets is resolved in a different way, or the information gets stale for some other reason. Whatever the reason, it means that the manual can get filled up with old, sometimes inaccurate and contradictory information and every so often this information needs to be refreshed.

New format documentation

In the most recent pass of updating the documentation I've taken a different approach, I am breaking the documentation into two main groups.

Core Documentation

The first is creating distinct, individual documents that cover Jomres as a whole, themselves broken into 3 separate docs : Installation, Site Administration and Site Customisation/development. These are currently available as PDFs which can be downloaded from the Documentation page in the main menu above. The first 2 have been translated to Spanish, Italian, French, German and Ukrainian. The third is a much more technical document and automated translation tools tend to mangle that a lot so it's (currently) only presented in English.

These docs mainly address concepts that require exposition and discussion. However much I try, Jomres will never be "simple" to use, and there are times when I just have to ask you to read a little.

I haven't yet created a Property Manager's guide, and I'm in two minds whether or not to create one. Half of me thinks that if I need to write a document for that, then I'm not doing a good enough job of making Property Management easy for managers. If I do decide to create a Property Manager's guide then I'll most likely deliver it as a .docx file, as well as or, or instead of, a PDF. A regular requirement for site admins is that they be able to white label Jomres. I have no problem with that, and giving managers a base document that they can modify and translate and rebrand as their own could be a useful tool for them.

Plugin Documentation

If you are familiar with the manual at jomres.net/manual you will know that the plugins section isn't easy to navigate. The menu system there is automatically generated and I can't easily change the order of menu options for that section alone.

Secondly, plugins often get as much, or more attention, than Jomres Core. They're an essential tool for anybody wanting to build a hotel and villa booking website so I have spent a lot of time building functionality in Jomres Core that allows the Core to present information about the shortcodes that each plugin offers, and pushing these shortcodes. This means that instead of overwhelming site admins and site designers/integrators with lots of potential shortcodes that can't be used on their sites, the Core lists only those shortcodes the site actually can offer, because the relevant plugin is installed.

The problem comes with converting plugin changes back to the documentation at jomres.net/manual. When a change is added I have to remember to go back to the documentation site and update the docs website with those changes. If I've updated a handful of plugins at a time, it becomes easy to forget the intricacies of those changes (especially after a long day of coding and my brain is frazzled and I just want to walk the dog and open a beer and decompress). Sometimes changes get added to the plugin info file which is used in the Plugin Manager to provide information about the plugin but that's a poor way to deliver information. The modal popup isn't very big and it's just not particularly readable.

The solution has been to create documentation within the plugin itself. This is included with the plugin and I can update it as I develop/maintain it. This means that the plugin's documentation is going to be much more up-to-date than the information in jomres.net/manual.

The Plugin Information Plugin

Most (not all) plugins now have their own copy of a file called README.md. The Plugin Information Plugin is designed to find all plugin's README.md files and present the contents of these files in a new menu option in Administrator > Jomres > Dashboard > Plugin Information

In WordPress the menu options for the plugins is in a sidebar (currently, that may change) and in Joomla 4 they're presented as buttons across the top of the page with the documentation underneath them.

These docs include screenshots and sometimes videos. Code examples, where relevant, can be presented nicely formatted, which makes them much more readable.

 

 

plugin info example

 

Moving forward all plugins will have their documentation delivered in this fashion. It's a far better tool for users, it doesn't overwhelm you with information about plugins you haven't installed and used in conjunction with the Shortcodes page I believe that there will be just enough information available to help you to do your jobs.

 

Wrapping up

Jomres isn't a static tool, it's constantly evolving and changing. The documentation evolves with it, and I hope that you will agree with me that these new changes will present you with all of the information you need, and no more, in a format that's useful and easy to use.

Over time I will eventually depreciate the manual at jomres.net/manual. It's done it's job, but now it's time for something new and (I hope) better.

 

 

 

 

 

 

 

Documentation, Plugins