By accepting you will be accessing a service provided by a third-party external to https://magazine.joomla.org/
Building Joomla Web-Help Systems - Part 1: Choosing an Environment
This is the first in a short series of articles intended to help technical writers and instructional designers learn how to build Joomla web-help systems. However, if you’re not a professional writer, you may still have an interest in the topic. For example, maybe you’re a one-person development shop, or you work for a small company without technical writers, and you want to write and publish your own software documentation. If you fall into the latter category, you will find these articles are geared toward beginners, as most writers will have less experience with Joomla. But, I hope they will give you a few ideas on how you might build your own publishing platform.
The first step in the process of building a Joomla web-help system is choosing the environment where your sites will reside. Joomla requires a web server, PHP, and a database (MySQL is typically used, but other database servers are supported). For those of you who have never worked with websites or servers, setting up a publishing platform that meets these requirements could seem intimidating. However, I can assure you that options are available to make this part of the process easier than you imagine. For instance, many hosting companies provide all required server software, as well as Joomla, and you can have a site up and running in a few clicks.
In the following sections, I describe some of the environments you can set up for a Joomla web-help system. I start with production environments, which will host your live web-help sites. Next, I cover learning and development environments, where you can work with Joomla without worrying about “breaking” it. Finally, I mention a couple of other environments that you may need to consider setting up if you work for a larger software development company.
Please note that the purpose of this article is to list and describe the environments where you can install Joomla. In the next article, I’ll cover options for installing it in each environment.
A “production environment” is a system that hosts one or more live Joomla web-help sites. Customers will be able to access your live sites from the Internet, or from Help menus and buttons in your software applications, or from both.
Using a hosting provider
If your company does not have the ability to host its own servers, or you are not comfortable with the idea of installing the required software on your own servers, or you can’t talk your IT department into building a system for you, then use a hosting provider for your production environment. If your company already has a corporate website with a hosting provider, you may be able to add your Joomla web-help sites under the corporate domain.
If your company doesn’t have a hosting provider, you’ll find most providers offer very reasonable rates. With a quick search, I found companies that provide customers with unlimited web sites (under a single domain) with unlimited MySQL databases for $5 - $10 USD per-month. However, with some of the cheaper companies, your Joomla sites could reside with hundreds of other sites on the same server. Another option is to use a company that specializes in hosting Joomla sites, which may provide dedicated server space, easier installation options, and better support; though, they may be slightly more expensive.
If possible, choose a hosting provider that registers domain names for its customers (most companies do this) and that specializes in hosting Joomla sites. In this scenario, you can have a Joomla site up and running with very little effort.
Using servers or virtual machines (VMs)
If your company is large enough to host its own servers, or has a data center, this is an ideal environment for a production Joomla web-help system. However, you’ll either need to configure the servers and install the software yourself, or you’ll need to convince your IT department to perform these tasks for you.
Purchasing your own servers is the most expensive option. However, to be more efficient, many companies now deploy VMs on their server hardware, which means if your company hosts its own servers, you may end up with VMs on a physical server.
My current production system consists of three VMs on a server in one of our corporate data centers. The proposal I wrote for developing the Joomla web-help system for my current employer described a low-cost solution:
- VMs on an existing server: no cost
- CentOS operating system on the VMs: no cost
- Joomla: no cost
The real cost associated with setting up the system consisted of the time, and therefore wages, it took for our IT department to deploy the VMs (almost no time at all) and for me to configure the servers, which took a couple of weeks.
Learning and development environments
The purpose of setting up a learning and development environment is to have a system where you can learn how to use Joomla and perform other tasks like installing plugins and extensions, customizing templates, and testing upgrades without worrying about “breaking” Joomla. If you use a hosting provider for your production environment, you’ll benefit from having a secondary learning and development environment.
Using a spare computer
While not a requirement, I highly recommend building a learning and development environment on a spare computer if you have one instead of installing it directly on your working computer. If you break Joomla while experimenting, which I have done a few times, you can just start over. On my development environment, I typically have multiple versions of Joomla running with various extensions and templates.
Using a USB thumb drive
I mention this option in case you are interested in learning about Joomla – how it works, and whether it might suffice as a publishing platform – without having to install it on your computer, purchase servers, or open an account with a commercial hosting provider. You can do everything with Joomla on a thumb drive that you can do on a computer or server. However, if, after trying Joomla on a thumb drive you decide you like it, consider transitioning to a spare computer, because Joomla’s performance will be much better.
Depending on the size of your organization, your development and QA teams may ask you to set up systems in their environments for integration and testing purposes. For example, a couple of our development teams asked me to set up Joomla web-help sites in the development environment to test the integration process. When they saw how easy it was to integrate a software application with a Joomla web-help site in development, they knew the process would work in production. It was worth the effort to set up the extra sites, because it gave the developers peace of mind, which ensured the success of my Joomla web-help system.