Authoring Documents for www.irchelp.org

This is an early draft of this guide, documenting the new way we’re going to maintain www.irchelp.org. Suggestions are welcomed. Unless otherwise noted, this really isn’t set in stone yet, so now is the time to give your input!


Introduction

This site is run by a group of volunteers primarily consisting of the ops from the #irchelp channels on EFNet and Libera.Chat. We welcome contributions to the site, but have a number of guidelines which you should follow so that your content can be easily included into the site.

Technical Information

As of 2012, all content on the site is maintained as Markdown files with a short YAML header containing metadata. Markdown is a simple way of adding formatting to text files, very similar to wiki markup.

The files are kept in a Git repository on GitHub, and automatically generated using Jekyll.

Our public git repository is located at https://github.com/irchelp/irchelp.github.io

The Git repository is very important to this process - it’s the part that will allow multiple editors access to update the site, without risk of stepping on each other’s toes, and which will allow us to easily roll back unwanted changes.

Document Header

The document header (YAML Front Matter) is written in YAML, and delimited with three dashes. It is a simple list of name: value pairs that describe each document. These headers will be used in templates.

A sample header follows:

---
title: Document title
author: random-irchelper
datecreated: 1 September 1993
dateupdated: 30 November 2012
status: (this is optional, but I'm going to add hooks that put a warning message about depreciated content if the status is "historical")
layout: default
license: (see below under legal requirements)
summary:	>
	This is a long summary with multiple lines. This is also optional.
	Each line is indented in the same way. When the indentation stops, so does the summary.
---

Note the — at the beginning and end of the header. This seperates the header from the content, and is required for Jekyll to recognize this as a header. The header is not Markdown formatted, so most other Markdown parsers will not format it.

Everything but the title: and layout: values are technically optional, but documents must have the YAML Front Matter prepended to them for Jekyll to recognize them as files it should process.

Useful tools

Several programs are useful to irchelp.org authors.

This list is by no means comprehensive, but it’s a good starting point for authors looking for tools.

Content Guidelines

Most of our current content was either authored by IRCHelp channel ops specifically for irchelp.org and made available on an “all rights reserved” basis, or used by permission, and we do not have the rights to relicense it.

Going forward, in the interests of license clarity, as well as to protect ourselves from any legal trouble and avoid having to scramble to remove articles, we need to have clear rights to use all content on irchelp.org.

There are two options for this:

The preferred license for new irchelp.org content is the Creative Commons Attribution-ShareAlike 4.0 International (CC-B4-SA) license. This license requires that the license be preserved intact when reusing or republishing content, and that content must be attributed back to original authors.

In any case, content must either be your own work, so that you have a clear right to license it, or it must already be under an appropriate free documentation license.

Preferred Licenses

Other Acceptable Licenses

Other licenses that we find acceptable include any of the following:

Other licenses may prove to be acceptable, but we will need to evaluate these on a case-by-case basis in the future.

Acceptable under Special Circumstances

License Tags

The applicable licensing tag should be indicated in the YAML front matter of each document, as one of the following values.