Difference between revisions of "Resources/Documentation/Contribute"

Revision as of 12:34, 26 June 2015

Main Page > Resources > Resources/Documentation > Resources/Documentation/Contribute

This page describes ways in which members of the AtoM community can contribute to our public documentation - the AtoM User and Administrator's Manuals available at https://www.accesstomemory.org/docs. For more information about the documentation platform we use, and why we chose it, see: About our documentation.

Contributing documentation to the AtoM project

Want to help us improve our documentation? All AtoM documentation is publicly available under a Creative Commons Attribution-ShareAlike 4.0 Unported licence (CC BY SA). We rely on our community of users to help us keep our documentation clear, comprehensive, and easy to use - if you see something missing or broken, or have an idea about how to improve or expand upon our existing documentation, please consider getting involved. There are three main ways you can help AtoM improve its documentation:

• #Suggest minor fixes to Artefactual
• #Contribute documentation yourself
• #Contribute translations

Also, check out our Documentation contribution guidelines

Suggest minor fixes to Artefactual

See a typo or a broken link? Have a question or a minor suggestion? If you've noticed something that can be improved in our documentation, but don't have the time or resources to fix the problem yourself, we want to hear from you!

Contact us at: webmaster@accesstomemory.org

Contribute documentation yourself

Is there a section missing from our documentation that you'd like to see? Or a section that you'd like to improve by adding clearer instructions, more screenshots, or alternative workflows? Help us improve our documentation by submitting new or revised content yourself!

The following instructions will show you how to contribute changes to our documentation straight from our GitHub repository (here), using GitHub's user interface (GitHub Flow), which provides all the tools you need - including a text editor! If you are a more advanced user, you can do this from your own computer using a text editor and the command-line - see GitHub's incredibly useful Help documentation for guidance.

An overview of the steps (described below):

• #Find the document you want to edit (or the place to add a new one)
• #Use GitHub's editor to make changes or additions
• #Commit the changes
• #Submit a pull request to Artefactual
• Dance! You've helped!

Find the document you want to edit

(Or the place to add a new one)

1. First, sign into your GitHub account at https://github.com (if you don't have an account yet, you'll need to create one first. You can do this on the same page.)

2. Navigate to Artefactual's AtoM Documentation repository: you can do this through the user interface by typing artefactual/atom-docs into the search bar at the top of the page:

3. GitHub's user interface provides a graphical file-explorer to help you navigate through the text files in our documentation repository. The AtoM documentation repository's files are organized into folders that mimic the structure of the user manual found on the home page - for example, all files that relate to the User Manual section called "Add/Edit Content" are grouped together in a file called "add-edit-content". In GitHub, click on a folder to view its contents. Click on a .txt file to open it in-page.

An image GitHub's repository browser

Tip

Can't find the right spot in GitHub? Don't forget to check the "Branch" drop-down - atom-docs is organized into several different branches, with the About/Contribute and FAQ docs on a different branch than the User and Admin manuals. Additionally, as we create new versions of our documentation for each major release, we will create new branches (2.0, 2.1, 2.2, etc) - so make sure you are editing or adding to the correct branch! Ideally, you will add fixes to the most recent docs, so we can carry those improvements forward.

4. If you are adding a new page, navigate into the correct folder, and click the "Add" icon next to the file path at the top of the page.

An image of the GitHub "Add file" option

5. If you are editing an existing page, navigate to the correct reStructuredText file, so that you can see its contents previewed on GitHub's interface. Then, click the "Edit" button found above the file preview:

An image of the GitHub "Edit" button

Tip

If you find it easier to navigate to the document you want to edit on the Access to Memory website, we've included a link directly to the related page in our GitHub repository in the right-hand navigation bar. You can find the page here on our website, and then click the "Source code" link in the sidebar - AtoM will redirect you to the relevant file in our atom-docs.git repository.

6. GitHub will create a copy of the entire atom-docs repository in your chosen location (or in your own new repository if this is your first time using GitHub). Now you can edit to your heart's content without fear of breaking our production website or making the documents unavailable to other users. In git, this is known as "forking". At the top of the page, you'll see that now atom-docs is in your own repository (indicated by your chosen user name). You'll also see this message above the file editor, to remind you:

An image of the GitHub header message after a successful forking

Use GitHub's editor to make changes or additions

7.

Commit the changes

Submit a pull request to Artefactual