Formal Documentation (Project)

Part of the ITSLM objectives is the creation of formal documentation based on the community input gathered through its website and wiki. This is the project to enable that transformation.

Objectives
To take the community input provided through the ITSLM website and wikis and convert it into a set of coherent documentation summarising best practice and recommending standards back to the community.

Motivation
Anticipating that the wiki will collect a lot of great information the ITSLM cooperative is keen to convert this into coherent documentation that can be used by individuals.

While the wiki is an excellent source of points of information it can be difficult to read a wiki as a coherent whole (they tend to jump around a lot and, let's face it, they can be confusing). Taking this information, organising it and presenting as a coherent set of documents will allow new users to leverage all of the information available through the wiki.

Documentation Format
Documentation will be written using LaTeX and produced in a number of formats including the following.


 * PDF
 * ePub
 * HTML
 * MS Word
 * ODF
 * Paperback (through one or more on-demand publishers)

And probably the following (the limiting factor being licensing issues).


 * iBooks

WTF is LaTeX?
LaTeX is a macro language extension of TeX, a typesetting language developed by Donald Knuth. LaTeX became popular in academia because of its powerful mathematics typesetting capabilities.

Although word processors have gradually adopted more advanced typesetting capabilities they are still word processors first and typesetters second. There is still a considerable and noticable difference between properly typeset output (as produced by LaTeX/TeX) and that output by wordprocessors like MSWord.

Why LaTex?
The TeX/LaTeX (pronounced 'tech' or 'lay-tech', the 'X' is a stand-in for the greek letter Chi) format is text based, therefore anyone can edit it with any text editor. Specialised editors are available, these help with the markup language, some offering more advanced features for test rendering or even WYSIWYG.

For those who prefer WYSIWYG the following tools may help (although you are envouraged to learn LaTeX, it's immensely powerful once you've learned it).


 * LyX

LaTeX/TeX is platform independent (there are LaTeX/TeX processors on most modern platforms) and can output in many different formats, it is ideal for our purposes.

LaTeX has many other features useful to our purpose.


 * Powerful indexing (both inter- and intra-document).
 * Citation system (for producing bibliographies and citations within documents).
 * Easy to define and modify the look of complete document sets without any modifications to the text itself.
 * Users who want to write without adding markup can do so (editors can add the markup afterwards).
 * It's quick to learn the basic markup (takes a while to learn the detail, but most people don't need to know the detail).
 * If you can use a text editor, you can write for LaTeX.

And, of course, it's Open Sourced and free to use.

Document Storage
Documents will be stored in their LaTeX source form in a GitHub repository.

Document products will be available through the main ITSLM site.