Resources/Documentation/Contribution guidelines - Revision history

Samason: /* Questions? */

2025-07-03T13:02:51Z

‎Questions?

Samason: /* Before contributing */

2025-07-03T13:02:22Z

‎Before contributing

Aseles: /* Contribution guidelines */

2022-12-06T14:42:06Z

‎Contribution guidelines

PeterVG: fix Artefactual typos

2020-06-26T22:45:30Z

fix Artefactual typos

Dan: /* Style guide */ Move "Questions" section out of Style guide

2018-11-07T22:39:32Z

‎Style guide: Move "Questions" section out of Style guide

Dan: /* Structure and project organization */ Further adjustment to image sizes

2018-11-07T22:22:20Z

‎Structure and project organization: Further adjustment to image sizes

Dan: /* Structure and project organization */ Adjust left image size

2018-11-07T22:21:17Z

‎Structure and project organization: Adjust left image size

Dan: /* Structure and project organization */ Fix image link

2018-11-07T22:19:10Z

‎Structure and project organization: Fix image link

Dan: /* Structure and project organization */ minor formatting fix

2018-11-07T22:17:40Z

‎Structure and project organization: minor formatting fix

Dan: Overhaul the contribution guidelines!

2018-11-07T22:16:56Z

Overhaul the contribution guidelines!

Show changes

@@ Line 505: / Line 505: @@
 ==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 [mailto:webmaster@artefactual.com webmaster@artefactual.com], or make a post in the AtoM [https://groups.google.com/forum/#!forum/ica-atom-users User Forum]!
+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 [mailto:contributors@artefactual.com contributors@artefactual.com], or make a post in the AtoM [https://groups.google.com/forum/#!forum/ica-atom-users User Forum]!
-<admonition type="seealso">
+<admonition type="see also">
 * [[Resources/Documentation/About|About the AtoM documentation]]
 * [[Resources/Documentation/Contribute|Contribute documentation]]

@@ Line 49: / Line 49: @@
 '''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 [[Resources/Documentation/Contribution_guidelines#Structure_and_project_organization|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 [https://groups.google.com/forum/#!forum/ica-atom-users User Forum], or email us at [mailto:webmaster@artefactual.com webmaster@artefactual.com] to let us know, and we'll file a bug report and follow up on it.
+'''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 [https://groups.google.com/forum/#!forum/ica-atom-users User Forum], or email us at [mailto:contributors@artefactual.com contributors@artefactual.com] to let us know, and we'll file a bug report and follow up on it.
 ==Structure and project organization==

@@ Line 22: / Line 22: @@
 Looking for instructions on how you can contribute? Find them here:
-* [[Resources/Documentation/Contribute|Contribute documenation]]
+* [[Resources/Documentation/Contribute|Contribute documentation]]
 There are a number of ways you can help improve the documentation, even if you don't have the time to improve them yourself! These include:

@@ Line 62: / Line 62: @@
 These correspond to three top-level directories in the AtoM [https://github.com/artefactual/atom-docs 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 Artefacual, 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 [mailto:webmaster@artefactual.com get in touch] with us directly, or make a post in our [https://groups.google.com/forum/#!forum/ica-atom-users User Forum].
+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 [mailto:webmaster@artefactual.com get in touch] with us directly, or make a post in our [https://groups.google.com/forum/#!forum/ica-atom-users 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 [https://github.com/artefactual/atom-docs code repository], this is represented as '''branches''', which you can see using the dropdown on the GitHub code repository page:
@@ Line 104: / Line 104: @@
-'''(3) - The User manual index page:''' As mentioned above in '''(2)''', each manual has its own <code>index.rst</code> 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 Arteactual developers, is organized slightly differently: each chapter has its own sub-index (an <code>index.rst</code> 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 <code>admin-manual/index.rst</code>) 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.
+'''(3) - The User manual index page:''' As mentioned above in '''(2)''', each manual has its own <code>index.rst</code> 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 <code>index.rst</code> 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 <code>admin-manual/index.rst</code>) 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.
 <admonition type="important">

← Older revision		Revision as of 22:39, 7 November 2018
Line 504:		Line 504:


−	===Questions?===	+	==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 [mailto:webmaster@artefactual.com webmaster@artefactual.com], or make a post in the AtoM [https://groups.google.com/forum/#!forum/ica-atom-users User Forum]!		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 [mailto:webmaster@artefactual.com webmaster@artefactual.com], or make a post in the AtoM [https://groups.google.com/forum/#!forum/ica-atom-users User Forum]!

@@ Line 81: / Line 81: @@
 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 [[Resources/Documentation/Contribution_guidelines#Style_guide|Style guide]]. First, a more detailed overview of the full project structure.
-[[File:docs-structure.png|left|285px|frameless|A detailed annotated image of how the AtoM documentation is structured]]
+[[File:docs-structure.png|left|240px|frameless|A detailed annotated image of how the AtoM documentation is structured]]
 To the left is an annotated image of the AtoM documentation structure as seen in a [https://en.wikipedia.org/wiki/Source_code_editor 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 [[Resources/Documentation/Contribution_guidelines#Style_guide|Style guide]].
@@ Line 93: / Line 93: @@
 '''(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:
-[[File:docs-contents.png|center|400px|frameless|An image of the contents.rst file in a text editor]]
+[[File:docs-contents.png|center|200px|frameless|An image of the contents.rst file in a text editor]]

← Older revision		Revision as of 22:19, 7 November 2018
Line 71:		Line 71:
	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 [https://www.accesstomemory.org/docs/latest/ documentation homepage]., For example, the User manual has chapters such as Overview, Getting started, Access content, Add/Edit content, etc.		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 [https://www.accesstomemory.org/docs/latest/ documentation homepage]., For example, the User manual has chapters such as Overview, Getting started, Access content, Add/Edit content, etc.

−	[[File:docs-~~chapter~~.png\|center\|330px\|frameless\|An example of how the AtoM documentation is structured within a manual into chapters]]	+	[[File:docs-chapters.png\|center\|330px\|frameless\|An example of how the AtoM documentation is structured within a manual into chapters]]

@@ Line 64: / Line 64: @@
 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 Artefacual, 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 [mailto:webmaster@artefactual.com get in touch] with us directly, or make a post in our [https://groups.google.com/forum/#!forum/ica-atom-users 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 [https://github.com/artefactual/atom-docs code repository], this is represented as '''branches'', which you can see using the dropdown on the GitHub code repository page:
+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 [https://github.com/artefactual/atom-docs code repository], this is represented as '''branches''', which you can see using the dropdown on the GitHub code repository page:
 [[File:git-branch.png|center|385px|frameless| An image of the GitHub branch button]]
@@ Line 124: / Line 124: @@
 '''(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 <code>_build</code>. 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==