Latest revision as of 08:42, 6 December 2022

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. You can browse the current Glossary in our manuals here:

• https://www.accesstomemory.org/docs/latest/user-manual/glossary/glossary/

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? Learn more about the organization and structure of the documentation by carefully reviewing the section below, on Structure and project organiziation.

6. 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 make a post in our User Forum, or email us at webmaster@artefactual.com to let us know, and we'll file a bug report and follow up on it.

Structure and project organization

The AtoM documentation consists of three manuals:

• The User manual
• The Administrator manual
• The Developer's manual

These correspond to three top-level directories in the AtoM documentation repository

The manuals are meant to be stable. Changes at this level may also require layout changes to the documentation website. New top-level directories should not be added without first consulting Artefactual, who maintains the documentation. Generally, your contributions should have a place in one of these manuals - if you're not sure where, feel free to get in touch with us directly, or make a post in our User Forum.

We version our documentation with each major release (e.g. 2.3, 2.4, 2.5, etc), so users can look at the documentation most relevant to their local installation. In our documentation code repository, this is represented as branches, which you can see using the dropdown on the GitHub code repository page:

Inside each manual, contents are organized as Chapters and Pages. Chapters are represented as sub-directories within the parent manual directory, and generally correspond to the sections within each manual on the AtoM documentation homepage., For example, the User manual has chapters such as Overview, Getting started, Access content, Add/Edit content, etc.

Inside each Chapter, content is organized into Pages. Pages are individual reStructuredText documents, with an </code>.rst</code> extension.

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

Pages can have sections, lead by section headers, which can be linked throughout the documentation where relevant. A detailed overview of how to structure pages, sections, and section headers will be provided below in the Style guide. First, a more detailed overview of the full project structure.

To the left is an annotated image of the AtoM documentation structure as seen in a text editor. Below, you'll find a brief explanation of each element annotated in the structure image. Further details on how to work with each element will be included below, in the Style guide.

(1) - Main index: The root index.rst file is the AtoM documentation homepage you see when navigating to:

• https://www.accesstomemory.org/docs/latest

Any time you add a new page to the AtoM documentation, make sure you also add a link in the appropriate manual's section to the main index, so user can find your new page and navigate to it.

(2) - The contents file: This file acts as the master index for the project, telling Sphinx where to find all the manuals. At first glance, it doesn't contain much:

However, this page uses the Sphinx toctree directive to provide the overall structure to our documentation. To understand the importance of this, we recommend you read up in the Sphinx documentation about documentation structure and the table of contents directive:

• Sphinx: Defining document structure
• Spinx: The table of contents directive

This table of contents is pointing to several other index files in the project - all the manuals have their own index.rst files, which contain a toctree for the pages in that manual. So this contents page tells Sphinx the overall project structure - it starts with index (our homepage), proceeds with the User manual (the toctree here points to the index.rst file in the user manual, which in turn has its own toctree for all the chapters and pages in the User mnanual, etc.), then the Administrator's manual, and finally with the Developer's manual.

(3) - The User manual index page: As mentioned above in (2), each manual has its own index.rst file inside the relevant manual direcotry, which contains a toctree for the pages in that manual. Note that the Admin manual, which was created by the Artefactual developers, is organized slightly differently: each chapter has its own sub-index (an index.rst file within each chapter directory) listing the the ordering of pages for that chapter, while the User manual's index file lists every page across chapters for the entire User manual. Because of this, the master index page for the Administrator manual (found at admin-manual/index.rst) is much shorter than the User manual index, because the toctree there just points to the individual chapter indices, which each have their own toctree for pages found in that specific chapter.

(4) - The User manual directory: This is an example of one of the master directories for an entire manual. All pages in the User manual appear in sub-directories (chapters) nested within this parent directory.

(5) - A chapter directory: This is an example of a chapter directory - a sub-directory of the manual to which it belongs. All pages in the "Access content" chapter of the User manual (such as Search, Browse, Advanced Search, Navigate, etc) appear as pages (individual reST documents) nested within the relevant chapter directory. For more information on working with Chapters, see the section below in the Style guide on Chapters and Pages.

(6) - Chapter images sub-directory: Each chapter has its own images sub-directory. If you are adding an image to a new section of documentation, place the image in the images directory nested within the relevant chapter.

(7) - A page: Within each chapter you will find pages (individual reST files). All reST files should be nested within chapter directories, with the exception of the following:

• contents.rst - the top-level toctree for the AtoM documentation
• index.rst - the main index for the documentation, which acts as the homepage

For more information on working with Pages, see the section below in the Style guide on Chapters and Pages.

(8) - The build directory: The_build directory is where your HTML or other formats will be output. This is where you will look on your local computer to preview your documentation locally before pushing. For example, when you run the command to generate HTML, there will be an html subdirectory inside of _build. If you open it in your local host computer's file explorer, you'll see the same structure of the docs, but with HTML pages instead of reStructured Text files. If you double-click to open one, it will open in your browser, where you can preview how your edits look before pushing them to the code repository.

Style guide

In order to keep our documentation consistent across manuals, we ask that you respect the following conventions and best practices when contributing documentation to the AtoM project. For information on how to contribute to the documentation, see:

• Contribute documenation

Jump to:

• Maintain an 80-character-width
• Naming conventions
• Chapters and Pages
• Sections
• Links
• Images
• Admonitions
• Writing style

Maintain an 80-character width

There is a long-standing convention in code writing to restrict the max width of a page's content to 80 characters. This dates back to the days in which this was the maximum width of a punch card, and the maximum display width of many early terminals. Those reasons no longer apply, as our technology has changed - but it also has to do with readability and the way the human eye/brain processes text, and how many people prefer to work with half-screen windows alongside the eventual output, for reference.

An example of how the AtoM documentation is hard wrapped to 80 characters.

For further information on this, see:

• http://www.richarddingwall.name/2008/05/31/is-the-80-character-line-limit-still-relevant/
• https://stackoverflow.com/questions/4651012/why-is-the-default-terminal-width-80-characters

When you are adding new content, be sure to keep to the 80 character width, please! If you are editing your files in a local text editor, there are settings and packages that can help you - for example, setting a veritcal ruler line at the 80-character mark; or installing hard wrapping package (such as magic-reflow for the Atom text editor, or WrapPlus for Sublime Text) that will allow you to hit a combination of keys and automatically wrap to the right length.

Code blocks are the one exception to this rule. A line of code can extend beyond 80 characters since reStructuredText will not be able to parse a mid-line break. This will generally only be relevant in the Administrator and Developer manuals.

Naming conventions

Whenever you are creating a new .rst file, saving a new image, or adding a new :ref: anchor 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
• Avoid special characters like stop words, exclude any special characters (such as * $ ! & etc) from names.

You can take a look in our AtoM documentation repository here to look at the raw reStructuredText markup for examples.

When naming titles and section headers, Use sentence case - that is, capitalize the first word only.

Chapters and Pages

The section above on Structure and project organiziation outlines how Chapters and Pages are used in the new project. It is unlikely that you will need to add a new Chapter - most new features occur within an already-defined workflow, and could be added to an existing chapter. If you think the AtoM documentation needs a new Chapter in one of its manuals, we recommend that you first file an issue in our documentation repository for discussion.

A Page is an individual reST file, or reStructuredText file. reST files end with the extension .rst. All reST files should be nested within chapter directories, with the exception of the following:

• contents.rst - the top-level toctree for the documentation
• index.rst - the main index for the documentation, which acts as the homepage

Make sure you have carefully reviewed the section above on Structure and project organiziation before adding a new page. New pages should follow the naming conventions outlined above.

All pages should begin with an anchor, which acts as the linking mechanism for the page. Below the anchor there should be a title, which is title-cased and enclosed top and bottom by equals signs. Note that the equals signs should match the length of the title. The title should be followed by introductory text about the page.

.. _my-great-page:

===================
My Great Page Title
===================

Introductory page text goes here.

Whenever possible, try to keep all relevant content in a single page, organized into sections. 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 section 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.

Starting with an introduction

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. 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.

All pages should have a Back to the top link at the bottom of the page, which refers to the page anchor. Please remember to add one if you are adding a new page.

:ref:`Back to the top <my-great-page>`

Sections

To break up longer pages, use section headings. Section headings in reStructuredText are a single line of text (no line breaks!) with an underline adornment. Similar to the title, the underline adornment should match the length of the title. Section headings should be sentence-case.

Section headings should be preceded by an anchor, which are used to link to the section from anywhere else in the documentation, including this page's table of contents. All first-level headings should be listed in the table of contents and therefore require an anchor. Lower-level headings only require a heading if you would like to include them in the overall table of contents or link to them from anywhere else in the documentation. An example:

.. _my-great-page:

===================
My Great Page Title
===================

Introductory page text goes here.

.. _first-level:

This is a first-level section
=============================

Information about this section.

A second-level section
----------------------

Detailed information about this subsection. Note that this section does not have
an anchor as we aren't going to link to it from anywhere else.

.. _another-first-level:

This is another first-level section
===================================

Detailed information about this subsection. Note that this section does not have
an anchor as we aren't going to link to it from anywhere else.

reStructuredText allows you to use any non-alpha-numeric character for the underline adornment; however, pages must be internally consistent. The AtoM documentation has some inconsistencies across existing pages with the characters used for adornment, but going forward we will try to use the following:

• Title: === (overlined AND underlined)
• First-level heading: === (underline only)
• Second-level heading: ---
• Third-level heading: ^^^
• Fourth-level heading level: ###

Table of contents

Include a table of contents after the page's introductory text block, linking to the anchor for each major (i.e. first-level heading) section below. The AtoM documentation webpage will include a full table of contents for the page in a sidebar, but we want to give users a way to jump to the section most relevant to them. These types of tables of contents are built by hand. The table of contents should be preceded by the bolded phrase Jump to:, or something similar such as " On this page you'll find," etc. An example:

.. _my-great-page:

===================
My Great Page Title
===================

Introductory page text goes here.

**Jump to:**

* :ref:`This is a first-level section <first-level>`
* :ref:`This is another first-level section <another-first-level>`

.. _first-level:

This is a first-level section
=============================

Information about this section.

A second-level section
----------------------

Detailed information about this subsection. Note that this section does not have
an anchor as we aren't going to link to it from anywhere else.

.. _another-first-level:

This is another first-level section
===================================

Information about this section. This section has an anchor since it's a
first-level section that will be reflected in the table of contents.

Links

There are three different types of links we use throughout the AtoM documentation: external links (to another page on the web), internal links (to another section of the documentation), and glossary links.

External links

There are two primary ways to create external hyperlinks in reST - inline, and as hyperlink targets.

In the AtoM documentation we have previously used primarily inline links, but we are slowly converting all external links to use hyperlink targets, rather than embedded inline hyperlinks. This helps text blocks adhere to the 80-character limit, and also allows a link to be easily reused within a page.

Inline hyperlinks look like this:

Here is a link to the `AtoM website <https://www.accesstomemory.org>`__

Instead, going forward, style hyperlinks as a target, like so:

Here is a link to the `AtoM website`_. You can also refer to documentation
about the `Sphinx documentation generator`_.

At the very bottom of the page, create a list of external links. This list should be below the Back to the top link. This list does not need to adhere to the 80-character limit. You can reuse the target anchor throughout the page as needed, and it will automatically add the hyperlink to your text.

.. _`AtoM website`: https://www.accesstomemory.org
.. _`Sphinx documentation generator`: http://www.sphinx-doc.org/en/master/index.html

Internal links

To create a hyperlink to another section of the AtoM documentation, use a reference label like this:

For more information on navigation using the Add menu, see: :ref:`Add menu <main-menu-add>`.

In the example above, main-menu-add is an anchor defined in another page from the same documentation repo - it's found in navigate.rst. Note that the display text can be different than the actual anchor target. If the Section header already contains the text you'd like to include, you can add a link without a label, like so:

For more information on working with archival descriptions, see: :ref:`archival-descriptions`.

When no display text is provided, Sphinx will automatically use the text of the related section title for display. In this case, it's the page title, which reads "Archival Descriptions" - suitable for our use without explicitly defining a different label.

Note that if necessary, you can also link to a page or section in the Archivematica documentation repositories. To do so, precede the anchor with either archivematica: or storageservice:. For example:

For more information on uploading content from Archivematica into AtoM, see:
:ref:`Upload DIP <archivematica:upload-atom>` for more details.

Glossary links

AtoM includes a lot of highly specific terminology and jargon - some comes from the archival profession, some from the development community and computer science, and some is AtoM-specific terminology we've developed to consistently refer to elements of the application and the user interface.

We want to make it easy for our users to find the content they need. Whenever you are using a term that appears in the glossary, use the :term: directive to link to it the first time it appers in a paragraph.

You can explore the current AtoM documentation glossary here:

• https://www.accesstomemory.org/docs/latest/user-manual/glossary/glossary/

Please familiarize yourself with it before you begin contributing, so you can refer to elements of the user interface consistently, and link to terms when relevant.

Term links work similarly to internal links in the documentation, except they don't need to follow the same naming conventions removing spaces:

On loading, the :term:`edit page` will first display the record with all
:term:`information areas <information area>` closed.

Generally, terms have been added to the glossary in the singular - so if you need to link a pluralized term, you'll want to add a label, e.g.

Only :term:`administrators <administrator>` can access the Settings pages.

If you need to add a new term to the Glossary, be sure to:

• Maintain the alphabetic ordering of the list
• Maintain the spacing and formatting of the page - otherwise you'll probably get an error when building
• Keep your explanation clear and as concise as possible
• Link to the most relevant section of documentation at the end of the definition whenever possible
• Include :term: links to any other terms you use in your definition, so users can easily navigate to them if needed

You can read more about working with Glossaries in Sphinx here:

• http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary-directive

Images

When possible, include a screenshot showing a key part of the action you are explaining that will help users understand AtoM's interface better. All images are placed in an "images" subdirectory that is shared by all pages in a chapter folder - for example, all pages in the Administer chapter's directory share a single images subdirectory. We prefer using PNG images, thanks!

Images must follow the naming conventions outlined above - spaces or special characters used in image names will cause errors during the build.

Here is an example of an image added in the AtoM documentation:

.. image:: images/description-collapsed.*
   :align: center
   :width: 85%
   :alt: An archival description with all information areas closed

Center-aligned images will display as a block (so text is broken above/below, and does not flow around it), while images aligned left or right will float, so that text wraps around them. If you are aligning an image to the left or right, you probably don't want a width above %50.

Please always add a description of the image using the alt attribute, to better support screen readers and give users a sense of what they are supposed to see if an image is broken or missing.

Note that an asterisk is used in place of the actual image file extension when using the image directive in reST.

If you want to include a caption with an image, use the figure directive - here's an example from the Navigate page:

.. figure:: images/breadcrumb-archdesc.*
   :align: center
   :figwidth: 80%
   :width: 100%
   :alt: An image of breadcrumb trail on an archival description

   An example of a breadcrumb trail (below the title bar)
   on a lower-level archival description

With Figures, the width attribute should remain at 100% - it's the figwidth attribute that determines the width the image will occupy on your page. The caption text appears after a full line break below the attributes, and in line with them.

If you are including images external to AtoM, make sure that you have permission to use and share the content you screenshot!

You'll also find some basic help on working with images in Sphinx here, and figures are covered in more depth in the reStructured Text documenation here.

Admonitions

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). Here are some examples:

Here are a couple examples of admonitions as they appear in the source reST files in the AtoM documentation:

.. SEEALSO::

   * :ref:`archival-institutions`
   * :ref:`edit-institution-theme`
   * :ref:`ISDIAH template <isdiah-template>`
   * :ref:`link-archival-institution`

.. WARNING::

   Deleting a description is a permanent operation that cannot be undone, and
   the associated data will be removed from AtoM's database. Be sure that you
   want to delete a record before confirming the operation.

Writing style

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.

Here are some general guidelines and reminders for tone and style:

• Write accessibly in clear, simple sentences intended for a global audience. Avoid colloquial language, humour, cultural references, and personal opinion. Keep your writing technical.
• Write from a second-person point of view. Use "you" and "your", not "my", "our", or "their".
• Avoid jargon and acronyms, if you can. Spell out acronyms at least once per page.
• Remember to link to glossary terms when first introducing them in a paragraph.
• Be consistent. Use the same consistently-formatted word or phrase for a concept throughout the documentation.
• Don't qualify or prejudge actions. Don't write that something is "easy" or "quick" as this is a deterrent if the user is not able to complete the action.
• Don't reference future development or features that don't yet exist.
• Remember to use sentence case for page titles and section headings.
• Use numbered lists for actions that happen in sequence.
• Use bulleted lists for most other lists.
• Truncate lines after 80 characters - more on this above
• Use serial (Oxford) commas (preferred, not enforced).

Questions?

If there's something that you're not clear about in these instructions, or you've run into an unexpected error, send us an email at webmaster@artefactual.com, or make a post in the AtoM User Forum!

Back to top

• Back to Documentation
• Back to Resources
• AtoM wiki home