Welcome to this guide about how to contribute to the website! I hope that this information is clear and answers any question you might have. If it isn't clear or you have any other questions then please let me know and I will try to edit and improve this guide for everyone.
The website is designed to be accessible to people with poor internet connections, and for use on mobile phones. As such, it has been heavily optimised for performance and speed. This means that some compromises have been made for ease-of-editing, but it's really not too hard and I can help out if you are ever stuck.
It's always useful when thinking about how the website should work and what content should be on the website to realise that our target audience:
- Might have very slow internet connections
- Will want content to be translated or easy to translate into different languages
- Might use all sorts of different devices, in particular mobile phones!
- Might arrive to the site and look for useful topics, but also might want to find content just by searching on Google or YouTube.
- Will almost certainly have a short attention span and want the best information to be clear and well signposted.
Technical Background
Introduction
The website is built on the content management system Grav.
Some of the advantages of Grav are:
- It is very fast.
- It is a file-based storage (as opposed to database storage), which is simple and means that it is very easy to manage backups.
- Grav is open source
The website is currently hosted by Rochen. They use litespeed servers, and the website takes advantage of the litespeed cache (this is the main reason that changes made to the website don't show up straight away).
Usage Statistics
The website uses Google Analytics for counting visitors and tracking which pages are most popular. A lot of our traffic is direct to pdf files from google search - this type of traffic is not counted by Google Analytics, but is counted separately.
I can add give you permission to view both Google Analytics and Google Search Console - please ask me if you would like to be added to these accounts.
Security
The website does not store sensitive information so I do not consider it as high-risk in terms of security. Some simple precautions are taken though:
- The site uses HTTPS rather than HTTP - this means that the connection between the user's computer and the server is encrypted.
- The website is fully backed up on Github.
- All passwords are securely ‘hashed’
The user accounts of all the editors are the only personal information stored. Therefore, the name, email address, and a hashed copy of the password are at risk if the site is hacked. For this reason it is important to not use the same password for this site as for your main Oxfam account!
Creating and Using your Account
Creating an Account for Editing Pages
Create an account on the website by registering using the below form. After creating an account you will not yet be able to sign in - let me know that you have created the account and I will be able to give you permission to log into the Admin panel and let you start editing pages.
Do not set your password to be the same one as you use for other Oxfam logins!
Working with the Admin Panel
Once you have an account and it has been ‘activated’, you will be able to log into the admin panel and start writing and editing content!
You might want to try the testing website before diving straight into the live website - see below.
Viewing your Changes
Any changes you make to the website go live straight away - be careful! If you are not sure about anything feel free to experiment with the ‘testing’ website first.
Sometimes you might not be able to see the changes immediately, however. This will probably be because the website makes a lot of use of caching to run as quickly as possible. If you can't see your changes there are two steps to take:
- Clear the cache on the website. Press the ‘clear cache’ button on the admin panel menu to clear the cache of the website kept on the server.
- Refresh the page in your browser. This will clear the cache that is held in your browser.
With these two steps you should be able to see your changes.
Testing Website
If you would just like to experiment with the site, you can use https://testing.oxfamwash.org/
This testing website is occasionally ‘reset’ to be the same as the main website, so really consider it like a playground.
To access the admin panel for the testing website follow this link: https://testing.oxfamwash.org/admin
The testing website is never cached (you might notice it is slower than the main site because of this), but that means that you will be able to view any changes you make straight away.
Writing Content
What content is appropriate?
There is no formal process for 'signing-off' on changes to the website. However, you should share with the advisors to ensure there is agreement on any changes.
These are my thoughts on what makes good content:
- The content is not fixed, so there should be no hestitation to remove content which is no longer useful, relevant or accurate!
- The website is not a library - only add the best, most authoriative content. Reviews, reports, lessons learned, webinars are generally not suitable. Although at first it appears as though adding more content can only be a benefit, consider that it distracts people from the definitive content that we want to show them! This website is not intended as a 'library' - good libraries for humanitarian work already exist: Policy & Practice for Oxfam documents, or UNHCR WASH or Humanitarian Library for example. Consider uploading the work there instead.
- Write using simple English. That is not to say simplify the content! There is a good guide about how to write in plain english on the Plain English Campaign website. Doing this will make it easier to read for non-native (and native!) speakers but also easier for automatic translation software, which is now built into some browsers.
- Prioritise Oxfam's content. Although it is appropriate to include other people's content if it is the best source. Make sure that we are allowed to distribute it though!
- Keep links to other websites to a minimum, as these often go out of date and will slow down the access to information for people with slow internet connections - better to just put the information directly on the page.
Writing / editing text on a page
Look at the text of existing pages to find out how to create any effect which you like.
To find the page that you would like to edit just click on it from the pages menu. Attention though: some pages are in folders and you need to click on the little arrow to see them in the folder (see below).
Editing text should be straightforward and self-explanatory.
You can install the browser plugin ‘Grammarly’, and this will spell check all of the content of the page for you (at least for the English language pages).
Headings should be used in a logical order to give sense to the page. The title of the page is heading 1, so the first heading on the page should be a heading 2.
Adding Files
A lot of the information on the website is contained in pdf or word documents. These need to be uploaded, and then are linked to from the page - just like a link to any other webpage.
Box.com This website does not use Box for any files. Please do not link to Box files - whilst these are good for secure internal Oxfam use Box links are not good for public sharing. They are slow for people with poor internet connections, and cannot be followed by Google, massively reducing the number of people who can find them.
Before uploading a file it is necessary to:
- Is a file really necessary? Files can be slow to download and are not easy to read on a mobile phone - if it's simple content or a summary consider writing it directly on the page.
- Compress the file. Most files are not made for publishing online and are unnecessarily big. Before uploading a file, put it through an online compression site, and you may see an enormous reduction in file size. This might not make a big difference to someone with a good internet connection, but for somebody with a weak internet connection this will make a huge difference. I have successfully used pdfcompressor.com for this.
- Rename the file. Try to not use any spaces in the file name, and replace them with
'-'characters. This will make it much easier to link to them. Also make the name neat and easy to identify, as this will be the filename that people will see in Google serach results, as well as when they download the file. - What file type is best? In general PDFs are of course good, but word or excel documents are useful for templates, for example monitoring forms.
Adding Images
Images can be added with a high quality and where needed the website will automatically create smaller images. Sometimes it's still useful to resize the images to around 2000 pixels width before uploading though, as resizing very large images larger than around 2-3 megabytes will require a lot of work from the server.
Make sure that any images used comply with Oxfam's image policies.
In general, it is easier to not try to control too much the display of the images - this is because the website will automatically be adjusting the display of the images for big screens (computers) and small screens (mobiles).
Adding Videos
Youtube is the preferred source for videos. Ideally add them to the Oxfam WASH channel. Either I can give you access to the account or I can help you with the upload if you prefer. Advantages of using YouTube include:
- The video is easy to find directly - for example in search results - so not all viewers will need to come to the website to find it.
- Very advanced video technology generally.
- Extremely good subtitle technology, with users able to adjust their display and automatic translation available.
- The 'plugin' for Grav which handles youtube videos is very well developed as it is by far the most popular.
Subtitles are great, and are best added as text files to youtube rather than to the video itself. Adding subtitles in this way has some big benefits:
- Subtitles are clear even when the quality of the video is low or it is on a small screen.
- The display of the subtitles can be adjusted by the user if they have particular needs.
- The subtitles can be automatically translated into other languages!
If you have gone to the trouble of adding good subtitles to your youtube video, you can set them to display by default by changing setting the option cc_load_policy to 1.
Advanced Technical Things
Getting Access to the Accounts for Managing the Site
There are various accounts associated with the website. You will need the username and password for:
- The cPanel to manage the server: https://www.oxfamwash.org:2083 (the username and password for this can be found on Rochen's site)
The domain name is currently with Amazon Web Services because I bought it before we got hosting. It might be easier if I moved this to Rochen, otherwise I can try to give access to this too.
With your email address I can give you permission to access the following:
- Rochen's website to pay for the hosting
- The GitHub backup of the site
- Google Analytics
- Google Search Console
- The Oxfam WASH YouTube account
Your user account on the admin panel can also be upgraded to ‘super user’ so that you can access all of the options. Most people are added with permission to edit the pages only, as changing other things is unnecessary and a bit overwhelming!
Regular Tasks
In addition to editing content, there are several things that need to be done to keep the website running:
- Regularly (weekly?) check in and make sure everything is still online and working
- Paying for the domain name to be renewed every year
- Every three years, paying for the shared hosting at Rochen
- Around monthly, logging into the grav admin panel and updating grav and plugins, then checking that nothing breaks afterwards
- If needed by Grav (this will be very rare), log into cPanel to update the PHP version
Understanding our Grav setup
Grav has comprehensive documentation, which is a good place to start.
Theming
The website uses a 100% custom theme which I've created. Feel free to dig in and make changes, but it will be intimidating for the uninitiated.
Litespeed Caching
The litespeed caching is turned on using the .htaccess file. All pages are
I created a small custom plugin to clear the litespeed cache when the cache is cleared.
Git for Backups and Local Development
The website has the 'git sync' plugin installed so that changes are automatically synced in both directions between github and the website.
It is possible to use the github repository to create your own copy of the website running only on your computer, which is useful if you want to make big changes to the whole site, or want to preview things before uploading. (Don't use git sync for this - just use normal git). If this is of interest, look at the grav documentation to get started running your own grav website.
CDN
The website does not currently use any content distribution network (CDN) as it is unlikely to be beneficial for a website with the level of traffic we have. It would be an advantage for users outside Europe if traffic increases significantly though.