Difference between revisions of "Workspace"

Revision as of 09:34, 13 May 2019

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 several ways you can help AtoM improve its documentation:

• Suggest minor fixes to Artefactual
• File an issue in our documentation repository
• Contribute documentation yourself via GitHub
• 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

File an issue in our documentation repository

If you notice a problem in the documentation, start by filing an issue in the AtoM documentation repository with as much detail about the issue as possible. This is a good thing to do whether you're just reporting a typo, or about to submit a whole new section of documentation. Also, just because you file an issue doesn't mean you're committing yourself to addressing the requested fix yourself! We're happy to receive reports about how we can improve the AtoM docs.

You can find the issues by navigating to the GitHub repository, and clicking on the Issues tab. You can look at any existing issues here for reference, and open a new issue by clicking the green button on the right side of the page:

An image of the the issues in the AtoM documentation GitHub repository

Give your issue a descriptive title that gives us a sense at a glance what to expect. The body of the issue should mention, at a minimum:

• The page (and section, if possible) where the problem occurs
• The version of the documentation you are consulting
• A proposed solution

Here is an example issue requesting a minor fix in the Administrator's manual, that you can look at as a reference:

• https://github.com/artefactual/atom-docs/issues/48

Contribute documentation yourself via GitHub

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!

There are two main methods of contributing new documentation. For smaller changes, it's easier to make your edits via GitHub's user interface. If you a more technically proficient user and you're working on a bigger contribution or would like to be able to work locally in a text editor before contributing your changes, we also have instructions on how you can configure the AtoM Vagrant box for documentation contributions.

Useful reference resources

• Sphinx documentation website
• reStructured Text primer
• AtoM documentation contribution guidelines
• How to write a commit message
• GitHub Help pages

Jump to:

• Contributing documentation via GitHub
• Contributing documentation using Vagrant

Contributing documentation via GitHub

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 our instructions below 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 GitHub 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.

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 "Create new file" button at the top of the page.

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 (a pencil icon) found above the file preview:

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:

Use GitHub's editor to make changes or additions

7. When you click the "Edit" button above the text file preview, a copy of the atom-docs repository is made in your repository (associated with your GitHub account), and you'll be redirected to a web-based text editor, where you can make changes to the file via your web browser. If you are adding a new page, the text editor will be blank when it opens, and you can begin entering text. As you work, you can click on the "Preview changes" tab to see a rendered version

8. Make the changes you want to the file. When you are done, scroll to the bottom of the page - next we will commit the changes.

Commit the changes

9. When you are finished editing and/or adding files in the text editor, scroll to the bottom of the page. You will see a box with several text fields to fill in before submitting your changes.

• Commit Summary: This is a required field. GitHub Help describes a "commit" as such: "Think of a commit as a snapshot of your project – code, files, everything — at a particular point in time". Your commit summary is a concise way to summarize the changes to the project that users will find in the commit. Commit summaries should be 50 characters or less: this is more like a brief title so users can determine what has taken place at a glance. Keep it brief and to the point. Check out these guidelines in the Git documentation.

• Extended description: This is an optional field, which we at Artefactual recommend using if you plan on editing our documentation. This is your chance to explain at greater length what the changes you made were, and why you felt you should make them. A concise message here will help us understand your work, and allow us to merge it into our documentation more quickly! Remember, you want to explain WHAT you did, more than why or how.

10. Once you've added a commit summary (required) and an extended description (recommended), click the "Propose File Change" button. GitHub will branch your changes, and redirect you to a page where you can compare the changes to the original, as well as submit a "pull request" to the AtoM documentation repository.

Submit a pull request to Artefactual

11. Once you've finished your changes and clicked the "Propose File Change" button, GitHub will redirect you to a new page. On the bottom half of the page, you'll see a "diff" - a graphical representation of the changes you've made - the red fields with the - minus symbol in the sidebar indicate content that was changed/removed, while the green fields with the + plus symbol in the sidebar indicate the new content that was added. When you submit your changes to Artefactual, we'll be able to see this too - it offers us a quick way to understand where you've made changes, what was changed, and why.

12. At the top of the page, you'll see your commit summary and description, with a reminder above it from GitHub (in blue) that the changes are still only in your repository. To submit them to Artefactual for inclusion in the AtoM documentation, click the "Send pull request" button on the right- hand side of the page.

13. The page will reload with information about your pull request - you can see a summary of what you want to merge where at the top of the page (i.e. your patch or fix into one of our documentation branches). Your commit message and summary will be below - we'll see a similar message on our end when we receive the request.

14. Artefactual will receive your pull request, and one of our team members will review the changes. If there's a problem, we can send you a message via GitHub, or even begin a discussion right on the code! This way, if there's something we don't understand about the changes you've made, we can connect with you directly. This is very similar to the code review process we undertake on code submissions from developers - see our Code review wiki page for more information.

You'll be able to see a summary of our changes and the status of the review on your pull request. We'll add comments if we have changes to request.

15. If you need to make changes, you can simply return to the files and edit them in place. Follow the same steps as above. When you submit your commit, GitHub will give you the option to submit it as part of your pull request. You can also reply on the PR comments thread to ask for clarification or help, or to let us know that the requested changes have been implemented.

16. Once we've accepted the pull request and merged it into our repository, you'll get a notification (you'll probably get an email too, unless you've changed your default GitHub account settings). You'll be able to see the status of any changes right on the pull request.

17. Success! Your contributions have been accepted, and merged into the AtoM documents. You should be able to go to our website and see them in the documentation. Thanks for helping out! We'll also close the related issue.

18. Finished! You did it! Thank you for helping to improve the AtoM documentation! It's time to dance!

Contributing documentation using Vagrant

For more technically proficient users who intend to work on larger changes, and/or simply prefer being able to work in a local text editor, the following instructions will guide you through the process of configuring the AtoM Vagrant box so that you are able to create pull requests against the public AtoM documentation repository.

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!

Contribute documentation translations

Want to help us translate these docs into your language? We rely on our amazing community volunteers to help us make AtoM a truly international application. Currently we are using Transifex to help us manage our project translations.

Back to top

• AtoM wiki home