Contributing

A few guidelines for submitting contents to the ALAN Wiki.

WIP NOTE — These guidelines are still work in progress. Suggestions are welcome.

---

Table of Contents

• Introduction
  • Important License Notice
  • Why CC0?
  • Getting Help and Support
  • About the Guidelines
• Conventions
  • Contents Format
    • Markdown
    • AsciiDoc
    • Other Markup Formats

---

Introduction

Anyone can contribute to the Wiki by adding new pages or editing existing ones, directly from the browser via the Wiki web-interface on GitHub.

Important License Notice

By contributing contents to this Wiki, you are donating your work to the Alan community via the CC0 1.0 Universal public domain dedication. This means that anyone will be free to reuse your submitted text, code and assets as they please, without restrictions.

For more details on the CC0 1.0 Universal terms, see the License page. For the full text of the CC0 license, see the file:

• COPYING

Why CC0?

Because this is a collaboratively-edited community-documentation, and we'd like its users to be free to reuse its contents in their own projects without having to deal with licenses conflicts or complications.

Getting Help and Support

This being a community project, feel free to ask for help if you need support with any technical problems you might be facing.

For questions and discussions, you can either:

• open an issue — for all matters directly concerning this Wiki and the ALAN repository.
• post on the ALAN Yahoo Group — for all discussion involving the ALAN community.

About the Guidelines

The goal of these guidelines is to preserve consistency across the Wiki, in order to simplify its maintenance.

Some guidelines concerning technical issues might be stricter than others, while others are just arbitrary conventions which are open to discussion and revision.

Conventions

Contents Format

Free-form plaintext documentation should be avoided in the Wiki! Obvious exceptions are the help output of command line tools, or excerpts from third party documentation, which can be included wrapped in a verbatim block.

Project maintainers need to be able to convert all documentation to and from the various markup formats at any stage, without having to manually format documents that don't adhere to well established standards.

Markdown

For consistency sake, the preferred format for Wiki pages is GFM (GitHub Flavored Markdown), using the .md extension. GFM is one of the most popular markdown flavours, and the de facto standard on GitHub.

AsciiDoc

Some Wiki pages might require advanced formatting features only available through AsciiDoc. If this is the case, then fine ... just create an AsciiDoc page with .asciidoc extension.

Other Markup Formats

If you are more familiar with other markup syntaxes, you may use anyone of the syntaxes listed in the table below, using the indicated file extension:

markup	flavour	extension
AsciiDoc	Asciidoctor Ruby	.asciidoc
Markdown	GFM	.md
ReStructuredText		.rst
Textile		.textile

Although the above table doesn't contain all of the lightweight markup syntaxes supported by GitHub, we've restricted the choice to the most commonly used syntaxes in order to avoid having to deal with a confusion of languages of Babylonian proportions.

The proposed file extensions are important for both consistency as well as for tasks automation by project maintainers.