About the AtoM documentation
Main Page > Resources > Resources/Documentation > Resources/Documentation/About
In August 2013, in preparation for the launch of AtoM 2.0.0, Artefactual Systems, lead developers of the AtoM project, began work to rewrite all project documentation and migrate it from a MediaWiki site to a new platform, using the Sphinx Documentation Generator as the new basis for the AtoM User Manual and Administrator's Manual. Sphinx is an open-source documentation generator that uses reStructuredText (reST) markup format as its basis, and converts reST files into HTML, PDF, and EPub formats. Sphinx was originally developed by George Brandl and publicly released under a BSD license in on March 21, 2008. reStructuredText (reST) is a lightweight markup language used in Sphinx documentation, written in plaintext using simple constructs to indicate the structure of a document, and which is human-readable in either raw (i.e. the text file itself) or processed (e.g. an HTML document, which can then be styled by CSS) form. reST was originally developed by David Goodger and released into the public domain on April 2, 2002.
The Access to Memory (AtoM ) project welcomes community contributions to its documentation. All AtoM documents are publicly released under a Creative Commons Attribution-ShareAlike 4.0 licence (CC BY SA), and we rely on input, contributions, and translations from our community to make our documents as useful and accessible as they can be. Information on how to contribute to our documentation is included here:
Why Move to Sphinx?
We saw a number of advantages to working with Sphinx, though it would slightly increase the barrier to community participation compared to the ease of a wiki. Some of the prime reasons are highlighted below.
Consolidation
Formerly, documentation for the AtoM project's earlier releases (under the name ICA-AtoM; read more about the history of AtoM and the ICA-AtoM project here) was broken up across several different wikis. It was not always easy for community members to find content, distinguish what was documentation from what was a development proposal, and whether or not the documentation was up to date or relevant to a particular release. This new documentation platform indicates a concerted effort by Artefactual Systems, lead developers of the AtoM project, to improve access to and ease of navigation within all project documentation and consolidate it to one platform.
Versioning
AtoM documentation is now maintained in a GitHub code repository (here). This allows us to fork the repository and create release-specific documents (e.g., 2.0 User Manual, 2.1 User Manual, etc.), and continue to make documentation for legacy versions available to our community. Previously, all documentation was maintained on a wiki; clauses were added for changes in newer versions and alternate screenshots for different themes. This made the documentation unnecessarily long and unclear to end-users. Now previous release documentation can be left unchanged so it remains relevant to the particular AtoM release, and users will be able to quickly locate documentation that is specific to the version of AtoM they are using.
PDF and EPub Formats
Sphinx is designed to allow the generation of multiple different formats from reStructuredText (reST), including Portable Document Format (PDF) and Electronic Publication (EPub). Our community users have long asked for documentation to be made available in PDF format - as part of our attempts to improve the accessibility of our documentation, we felt that Sphinx would allow us to meet these goals most easily. With these additional formats, users will be able to view and print documentation more easily, across a wider range of platforms and devices.