Revision as of 17:40, 26 June 2015

Main Page > Resources > Resources/Documentation > Resources/Documentation/Contribution guidelines

This page offers a overview of best-practice suggestions for contributing documentation. We strongly recommend reviewing this page before contributing to the AtoM documentation - thanks! This document covers how to structure and format contributions to meet the established conventions of Sphinx, and of our documentation structure. For information on how you can contribute, see: Contribute documentation.

Contribution guidelines

So you're thinking of contributing to our documentation? See something that needs fixing, or something that could be improved? Great! Below you'll find some helpful guidelines to get you started, and to familiarize you with the approach we have been trying to follow.

In general, there are two main types of contributions:

• General improvements: typo corrections, fixing broken refs or links, correcting inaccurate or out-of-date information, and offering better explanations through clearer writing and additional examples.
• New features or new pages: Adding a page of documentation that we haven't yet covered in our ongoing rewrite attempts as we move platforms, or documenting a new feature that has been added to AtoM since the last release.

We welcome both kinds of contributions from our users, and are always aiming to improve our documentation as much and as often as possible. To maintain a sense of consistency and quality over time, here are a few tips.

Before contributing

1. Understand that our documents are all released under a Creative Commons Attribution-ShareAlike 4.0 license (CC BY SA). This means that your contributions are being released to Artefactual and the AtoM community to use, share, remix, and distribute as they see fit, provided any distribution takes place under the same licensing. Your work will be a gift to the AtoM user community, and we thank you for it!

2. Read through some of the documents we've already created. You'll notice that there is a consistent structure to most of them, which we will describe in greater detail below. By reading through some of our existing documentation, you will get a feeling for the overall structure and style. By looking at the source code (there's always a link to the source code in the sidebar), you can see how we've used Sphinx to style and structure the page.

3. Familiarize yourself with Sphinx and reStructuredText before starting. As outlined above in our About our documentation section of the wiki, we are using the Sphinx Python Documentation Generator to produce the AtoM documentation. Sphinx employs reStructured Text as its markup language, and you'll need to understand how to use its syntax if you want to contribute. The "First Steps with Sphinx" (here) is a great introduction to some of the key elements of Sphinx, and the reStructuredText Primer (here) will introduce you to the key characteristics of reST.

4. Examine the AtoM documentation glossary. Over the years, we have been adding to the glossary in our User Manual in an attempt to be consistent with how we refer to different parts of the application. You should try to use the same terms to refer to different parts of AtoM in your contributions, and you should link to the glossary (using the :term: reST markup) whenever possible - in general, we try to link a term the first time it is used in any paragraph.

5. Make your contributions in the right place. Are you contributing to the latest version of our docs, so that these improvements will be carried forward in the next version? Are you looking to edit the Admin manual, but only able to find the User Manual? AtoM documentation is hosted on GitHub (here), and it is kept in multiple "branches" - we have a branch for every major release version of our software (e.g. 2.0, 2.1, 2.2, etc), where the User manual and the Administrator's manual are maintained together. We will also be creating a development branch, where all new documentation will be added, which may not be visible on the website until the release is available. Take a look around our repository or read the [[Resources/Documentation/Contribute contribution instructions] for more information. If you're going to submit documentation for the User or Admin manuals, make sure you're submitting it to the development branch, so it is included in our next version!

Here is an example illustration of the folder structure for the AtoM user manual in our atom-docs.git repository. All files in a chapter folder share a single images folder:

An example of how the AtoM documentation is structured within the repository

6. Examine our existing document structure and try to follow it: In our old ICA-AtoM User Manual wiki, each section was made up of multiple pages, leading to many unnecessary pages and making it harder to navigate or find a specific section. In our Sphinx rewrite we are trying to organize everything in a much simpler fashion - each chapter of the manual (e.g. Getting Started, Add/Edit Content, Administer, etc) has its own folder. Each article is usually contained in a single reStructuredText (.rst) file (rather than multiple linked files). So, for example, you will find all information about adding, editing, deleting, and linking archival descriptions in a single place - archival-descriptions.rst. By using the different header levels of reST, we define a structure to the page that is automatically converted into a table of contents in the sidebar. This keeps the documentation's organization simpler, and there is less searching to find relevant or related information. Similarly, a simple structure will allow us to easily convert the HTML documentation into PDF and ePub formats in the future.

7. Include images to help illustrate your instructions. When possible, include a screenshot showing a key part of the action you are explaining that will help users understand AtoM's interface better. Make sure that you have permission to use and share the content you screenshot! All images are placed in an "images" subfolder that is shared by all documents in a section folder - for example, all documents in the Administer folder share a single images folder. If you have trouble adding images using the instructions above, contact us at webmaster@artefactual.com and we can find another way to upload them for you. We prefer using PNG images, thanks! You'll also find some basic help on working with images in Sphinx here.

8. Try to keep your writing clear and concise. Your explanations should be comprehensive, but easy to follow. The more precise your writing is, the easier others will find it to follow. We also hope to have our documentation translated into multiple languages in the future - keeping it simple and to the point will reduce the workload in the translation process.

9. Use admonitions to support your work with key points or related materials. Sphinx and reST include a whole class of built-in admonitions, and we have styled several of these for inclusion in the documentation as necessary (we use the same ones in the wiki here as well). Take a look at the source code for of our docs to see how these are written in Sphinx. Here are some examples:

10. Test your actions in an instance of AtoM before documenting them. We recommend following along step-by-step in AtoM as you create documentation, so that you can screenshot the process as you proceed, and so you don't miss any steps. If you find a bug in the software, don't document the bug - let us know! You can file an issue ticket in our bug tracker, Redmine, make a post in our User Forum, or email us at webmaster@artefactual.com.

Contributing new documentation

If you are adding a new page to the documents, or a new section covering an undocumented feature in our latest release, it is extra-important that you understand how Sphinx is strucutured, and how have tried to organize and present the documentation. Here are a few guidelines to help get you started:

Understand how the Sphinx toctree directive works, and remember to add your new page to the relevant toctree For Sphinx to be able to parse all the documents and convert them into multiple formats (HTML, PDF, ePub), it requires a logical structure for all pages. Sphinx therefore uses a table of contents tree, or toctree to create a map of the structure. This means that whenever a new page is added to the documentation, it must also be added to the appropriate toctree.

An example image of the toctree found in user-manual/index.rst

Use the preferred naming conventions for files and :ref: labels When ever you are creating a new .rst file, saving a new image, or adding a new :ref: label above a section heading, please use the following conventions:

• Make it human-readable - The label or file name should be as close as possible to the name of the file or section it refers to. You can exclude stop words such as prepositions etc, but the label name itself should be meaningful.
• Use lower case letters - We are not using capital letters, or camelCase, when naming files and labels.
• Separate words with hyphens - A file about "Archival descriptions" can be saved as archival-descriptions.rst

You can take a look in our AtoM documentation repository here or use the "view source" link in the sidebar any page in our documentation to look at the raw reStructuredText markup for examples. Thanks!

Start with an overview We have tried to begin each page (and in some cases, each section) with an overview of the concepts, entities, and workflows involved in the chapter. See, for example, any of the pages in our User Manual's "Add/edit content" section. Check the User Manual Glossary for terms that can help you when doing this. We also like to refer to existing and relevant international standards, glossaries, articles, and other sources, such as:

• Any of the relevant standards of the International Council on Archives (ICA)
• The Society of American Archivists' Glossary
• The InterPARES 3 Terminology Database

* Any of the ICA's Multilingual Archival Terminology Database terms that can help guide you when doing this.

We are trying to make sure our documentation, and our AtoM development, is guided by relevant archival theory, standards, and best practices. Introducing these concepts is a great way to introduce a module in AtoM, and ensures that users understand not just how, but why.

Discuss how this is applied in AtoM Close the introduction by offering a brief overview on how the outlined theory is implemented in AtoM, what can/cannot be done using the AtoM module, and what will be covered in the following section.

Offer quick links to the key sections of the page Though a full table of contents will be available in the sidebar, it's useful to offer users links to the main sections of the document - this gives users a sense at-a-glance of what they will find on this page, and allows them to jump directly to relevant content.

Include comprehensive steps for every action Assume that a user will jump directly to a section without necessarily reading the documentation in order. Provide links to other parts of the manual - if you tell a user they can search for an archival description to edit it, provide a link to the "Search" documentation. Each section should stand on its own and be a complete and thorough overview of the steps required to produce a specific action in AtoM, but it should also point outwards to other relevant sections of the manual as needed.

Back to top