ASDSO Dam Safety Toolbox

Guidelines for Creating a Resource Page

From ASDSO Dam Safety Toolbox
Revision as of 20:31, 28 September 2023 by [email protected] (talk | contribs)
Jump to: navigation, search

Resource Pages provide a brief explanation of the purpose of the document and a brief summary of the content covered, as well as a link to view and download the latest edition of the document, links to view and download previous versions, and a section to include any errata or notes about the document. The typical organization of a Resource Page consists of the following items:

  1. Document title and document number, if applicable (this item is included in the title of the page)
  2. Authoring organization/individual(s) and date of latest publication edition
  3. Image of document cover
  4. Summary of document purpose and content
  5. Link to view and download latest version of the document
  6. Link to view and download previous versions of the document, if applicable
  7. Section for any errata or notes, if applicable (This section could include any changes between document versions, common uses, any sections that may have become irrelevant/outdated, etc.)


Whenever possible, it is preferred to create a Resource page for documents cited on the website, even if references are not publicly available and must be accessed or downloaded via external websites. These pages serve as a single point of reference for all associated topic pages to link to and will facilitate ease of maintenance for the website over the long-term.

Step 1: Adding a New Resource to the Catalog

The first step in adding a resource to the Dam Safety Toolbox is to add the reference to either the Best Practices Resources Catalog or the Other Resources Catalog. In general, a "Best Practices Resource" is a document that is highly vetted and widely accepted in the dam safety industry (e.g., federal agency documents). "Other Resources" are not as thoroughly vetted, but are still valuable resources for dam safety professionals. Examples of other resources include guidance documents and tools developed by state dam safety agencies, landmark technical papers, or academic research. Before a contributor adds the reference to the catalog, they should first ensure that the reference is not already on the site. Variations in name should be considered in confirming that the reference needs to be added. The website search function can be helpful in doing this.

To add a new reference to the appropriate catalog, either the the Best Practices Resources Catalog or the Other Resources Catalog page must be edited by adding the following code to the table:

|-
| Author || [[Title]] || Year of Publication

The reference should be added to the table in the following order:

  1. alphabetically by author (A to Z),
  2. numerically by date (newest to oldest), and
  3. alphabetically by title.


The title of the reference should not include the author or date of publication. In some instances, it may be appropriate to include a subtitle, document ID number, or chapter number in parentheses as part of the title.

Step 2: Uploading Files

When logged into the website, contributors have the ability to upload files. For Resource pages, contributors should upload both the document of interest and an image of the cover or other representative graphic from the document prior to creating the resource page. Learn how to upload documents to the Dam Safety Toolbox on this page. If documents are not publicly available, this step is not required.

Once a file has been uploaded, a page specific to that file will be created on the website that is named File:DocumentName.pdf and has a hyperlink in this format: https://damtoolbox.org/wiki/File:DocumentName.pdf. This hyperlink should not be used in linking to the new Resource page. The actual document can be opened from that page by clicking on the hyperlink with the file name. This will open the document in the browser with a hyperlink in this format: https://damtoolbox.org/images/#/##/DocumentName.pdf. This hyperlink to the actual document should be used when linking the new Resource page to the document. This will link to the actual file rather than opening another page on the website.

Step 3: Creating a New Resource Page

Once a reference has been added to the appropriate catalog, an accompanying Resource page can be created. Within the catalog, the title of the reference should appear as red text indicating that an internal hyperlink has been created, but the linked page does not yet exist. By clicking on the red title link, the contributor is taken to the content editor for the new resource page. The contributor then simply follows the instructions in the template below to complete the creation of the new Resource page.


Resource Page Template Code

The following template code should be copied and pasted into the editor when creating a new resource page to facilitate the process of creating, formatting, and reviewing new content. Users should not add or delete sections of code. If specific items are not applicable or unavailable, these fields should be left blank.

{{References Template

|author= <!-- Add author/publisher on blank line below-->

|date=<!-- Add publication year on blank line below -->

|picture= <!--upload a file to the site and reference it below in this format File:example.png-->
File:
|link= <!-- Add URL to document on blank line below (To retrieve URL for a PDF, upload document as a PDF file and copy link address of the actual file as uploaded to the website. Hyperlink should look like this: https://damtoolbox.org/images/#/##/Document Name.pdf)-->

|abstract= <!-- Add document summary-->

|versions= <!-- Add years (and links if available) of previous versions below. To add a link use the format [link.com 2004] -->

|errata= <!-- Add errata below with links if available [link.com 2004] or add "none" -->
None
}}



Revision ID: 7681
Revision Date: 09/28/2023