ASDSO Dam Safety Toolbox

Guidelines for Creating a Resource Page: Difference between revisions

From ASDSO Dam Safety Toolbox
Jump to: navigation, search
No edit summary
mNo edit summary
 
(2 intermediate revisions by one other user not shown)
Line 15: Line 15:


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.
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.
Watch the {{Video Icon}} [https://www.youtube.com/watch?v=WTweWFURJ-I Dam Safety Toolbox Tutorial: Creating a Best Practices Resource Page] for additional help.
    
    
== Step 1: Adding a New Resource to the Catalog ==
== Step 1: Adding a New Resource to the Catalog ==
Line 45: Line 47:


== Step 3: Creating a New Resource Page ==
== 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.
Once a reference has been added to the appropriate catalog, an accompanying Resource page can be created. An easy way to create a new page within the wiki is use the "Search Toolbox" utility in the header of the site to search for the exact title of the page you wish to create. If the page or something similar already exists on the site, it will open or appear within the search results. If the page does not exist, an option to create this page will appear at the top of the search results. 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 ==
== Resource Page Template Code ==

Latest revision as of 05:29, 18 January 2024


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.

Watch the Dam Safety Toolbox Tutorial: Creating a Best Practices Resource Page for additional help.

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 Best Practices Resources Catalog, the page must be edited by adding the following code to the table:

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

To add a new reference to the Other Resources Catalog, the page must be edited by adding the following code to the table:

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

For both catalogs, 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. An easy way to create a new page within the wiki is use the "Search Toolbox" utility in the header of the site to search for the exact title of the page you wish to create. If the page or something similar already exists on the site, it will open or appear within the search results. If the page does not exist, an option to create this page will appear at the top of the search results. 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 (if the document is copyright protected or otherwise unavailable, this image can use used: Image_Not_Available.jpg)-->
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: 7798
Revision Date: 01/18/2024