Contributing guide for community members

Before contributing to the documentation, please read the following pages:

• Technical details about the Archivematica documentation
• Style guide

These resources might also be helpful:

• reStructuredText Primer
• How to Write a Git Commit Message

Create an issue

If you notice a problem in the documentation, start by filing an issue in the code repository with as much detail about the issue as possible.

Note that you can file an issue without fixing it! We really appreciate it when you bring issues to our attention and will try to fix them as soon as we can.

Give your issue a descriptive title. If your issue describes an error in the documentation, start the title with the word "Problem", followed by a semicolon and a space. For example, issue 66 is titled "Problem: docs do not indicate new silent AIP compression behaviour", indicating that there is an issue in the documentation that needs to be solved. This convention is subjective; general suggestions for improvements to the documentations can omit the "Problem" prefix.

To create an issue:

1. Go to the Archivematica Issues repository.
2. Click New issue and select Documentation report template.
3. Fill in the fields in the template.

An example of a well-described issue is issue #267.

Create a pull request

All community members are welcome to propose changes to the Archivematica documentation by creating a pull request in GitHub. Artefactual staff will review your changes for content and style and may require changes before it can be merged into the documentation code.

1. Find the .rst file that you want to edit. If you wanted to edit the Administrator FAQ, for example, you would navigate to archivematica-docs/admin-manual/maintenance/maintenance.rst, which contains the FAQ.
2. Click on the pencil icon to edit the file. When the editor opens, a blue box at the top of the page will read:

You’re editing a file in a project you don’t have write access to. We’ve created a fork of this project for you to commit your proposed changes to. Submitting a change to this file will write it to a new branch in your fork, so you can send a pull request.

3. Make your desired changes. Please remember to consult the style guide before you write.
4. Include a commit message explaining the rationale behind your changes.
5. Click on Propose file change
6. You'll be taken to a page where you can compare changes and start a pull request. At the top of the page, ensure that the following information is correct:
   • Base fork: artefactual/archivematica-docs
   • Base: Branch of the documentation that you want to edit (e.g. 1.7).
   • Head fork: your-username/archivematica-docs
   • Compare: The branch place you made your edits. Often this is given a default name like patch-1.
7. Click on Create pull request to submit your changes.

If you are more familiar with GitHub, of course feel free to edit the .rst files however you choose!