ASDSO Dam Safety Toolbox

Guidelines for Creating a Topic Page: Difference between revisions

From ASDSO Dam Safety Toolbox
Jump to: navigation, search
No edit summary
mNo edit summary
 
(30 intermediate revisions by 4 users not shown)
Line 2: Line 2:
[[Category: Dam Safety Toolbox Formatting/Style Guide]]
[[Category: Dam Safety Toolbox Formatting/Style Guide]]
----
----
==Relevant Policies==
<noautolinks>Topic pages introduce a topic by providing relevant background information and peer-reviewed guidance. These pages are generally between 100 and 500 words in length. The purpose of these pages is not to document every formula and procedure relating to a topic, but rather to give an overview of the topic and point the user to Best Practices Resources where the topic is addressed in a more comprehensive manner.


Below is a list of policies relevant to the creation of a new Topic Page. Click to learn more.  
Where appropriate, headings should be included to organize and distinguish between subsections of a single Topic Page. If more than a few subsections are needed to convey the information for a single topic page, the creation of new subtopic pages for each of the subsections should be considered. This will help keep Topic Pages concise and focused, thereby increasing the ability to link between subtopic pages and reducing the potential for redundancies in content.


==Guidelines for Creating a New Topic Page==
Watch the {{Video Icon}} [https://www.youtube.com/watch?v=SmMctTfnz78 Dam Safety Toolbox Tutorial: Creating a New Topic Page] for additional help.


Naming a New Page
== Naming and Creating a New Topic Page ==
Care should be taken when naming a new Topic Page. Avoid simplistic titles or terms that can mean multiple things or apply to more than one discipline. Rather, names of Topic Pages should be as specific as possible. For example, if creating a page about the design of relief wells, the page should be called "Design of Relief Wells." If it was simply called "Design", this generic page title may inadvertently auto-link to other pages on the website where the term "design" is used but a link to the very specific topic of relief wells is not appropriate.


Topic Pages introduce a topic by providing relevant background information and peer-reviewed guidance that follows identified Best Practices Resources and are generally between 100-500 words in length. The typical organization of a Topic Page consists of the following items:
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. In cases where similar content or page titles already exist, the existing page should be edited where possible to avoid duplication of content. 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 page 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 topic page. The contributor then simply follows the instructions and template below to complete the creation of the new topic page.


# '''Topic title''' (this item is included in the title of the page)
== Typical Topic Page Content ==
# '''Introductory paragraph''' (and image if provided)
At a minimum, a Topic Page will include a page name/title and introductory text (e.g., a definition of a given term). A thoroughly developed Topic Page may include any and all of the following content:
#* <!-- Link to policy on using non-copyrighted media when subpage is created under main policies page --> ''[[Dam Owner Toolbox Policies and Procedures Guide | Click here for policies on using images.]]''
#* ''Click here for guidance on using the template for inserting images into Topic Pages''
# '''Topic Page Title''' (see section above regarding the importance of naming a new Topic Page)
# '''List of links''' to pages on related subtopics or '''Sections with Guidance on Related Subtopics''' (when content for related subtopics is short or limited). When content for sections with guidance on related subtopics is added, consider moving the content for these sections to their own subtopic page to prevent the parent topic page from becoming too expansive.
# '''Breadcrumb Menu Navigation Links'''
#* ''Click here for help with creating internal and external links''
#* ''[[Guidelines for Adding "Breadcrumbs" to a Page | Learn how to create breadcrumb menu navigation links]]''
# '''List of examples''' that illustrate the concepts explained in the previous section(s). These can be links to content on other websites such as ASDSO's DamFailures.org, news articles, videos, etc.  
# '''Introductory Paragraph''' (typically 100 to 500 words in length)
#* [[Creating an example Page | ''Click here for guidance on creating a new Example Page'']]
# '''Pertinent Figures or Images''' (for demonstrative or aesthetic purposes)
# '''List of Best Practices Resources''' that are applicable to the topic described and whose content may have been used in the creation of the previous sections.
#* ''[[Media and Copyright Policies and Guidelines | Learn about copyright law and the policies on using images on this site.]]''
#* [[Creating a Best Practices Resource Page | ''Click here for guidance on creating a New Best Practices Resource Page'']]
#* ''[[Guidelines for Using Templates | Learn how to use the picture template for inserting images into Topic Pages]]''
# '''List of Trainings''' that are applicable to the topic such as webinars, presentations, etc. and consist of more than just cursory or introductory information on the topic (if applicable).
#* ''[[Guidelines for Uploading New Files | Learn how to upload pictures and other files to the website]]''
#* [[Creating a Training Page | ''Click here for guidance on creating a new Training Page'']]
# '''Links to Related Subtopic Pages''' or '''Sections with Guidance on Related Subtopics''' (when content for related subtopics is limited).  
# '''List of citations''' (if any) used in the previous sections. ''Click here for guidance on using the Citations Template.''
#* ''[[Guidelines for Inserting Links | Learn how to create internal and external links]]''
#* ''Click here for guidance on using the Citations Template''
#* ''[[Guidelines for Using Templates | Learn how to create icons for document, website, and video hyperlinks]]''
# '''List of Examples''' that illustrate the concepts explained in the previous section(s). These can be links to content on other websites such as ASDSO's DamFailures.org, news articles, videos, etc.  
#* [[Guidelines for Creating an Example Page | ''Learn how to create a new Example Page'']]
#* ''[[Guidelines for Inserting Links | Learn how to create internal and external links]]''
#* ''[[Guidelines for Using Templates | Learn how to create icons for document, website, and video hyperlinks]]''
# '''List of Best Practices Resources''' that are applicable to the topic of interest. Best practices resources are defined as documents that are highly vetted and widely accepted in the dam safety industry (e.g., federal agency documents).
#* [[Guidelines for Creating a Resource Page | ''Learn how to create a New Best Practices Resource Page'']]
#* ''[[Guidelines for Inserting Links | Learn how to create internal and external links]]''
#* ''[[Guidelines for Using Templates | Learn how to create icons for document, website, and video hyperlinks]]''
# '''List of Other Resources''' that are applicable to the topic of interest. Other resources are not as thoroughly vetted as best practices documents, but are still valuable resources for dam safety professionals. Examples include guidance documents and tools developed by state dam safety agencies, landmark technical papers, or academic research.
#* [[Guidelines for Creating a Resource Page | ''Learn how to create an Other Resource Page'']]
#* ''[[Guidelines for Inserting Links | Learn how to create internal and external links]]''
#* ''[[Guidelines for Using Templates | Learn how to create icons for document, website, and video hyperlinks]]''
# '''List of Trainings''' that are applicable to the topic such as webinars, presentations, etc.
#* [[Guidelines for Creating a Training Page | ''Learn how to create a new Training Page'']]
#* ''[[Guidelines for Inserting Links | Learn how to create internal and external links]]''
#* ''[[Guidelines for Using Templates | Learn how to create icons for document, website, and video hyperlinks]]''
# '''List of Citations''' (if any) used in the previous sections.  
#* ''[[Guidelines for Inserting a Citation | Learn how to use the Citations Template to automatically populate a list of citations]]''
# '''Revision History''' should be included at the bottom of every page.
#* ''[[Guidelines for Using Templates | Learn how to add the revision history template]]''
 
 
==Resources, Trainings, and Examples==
When creating and updating a Topic Page, it is important to make sure that the content is supported by links to the best resources that are available about that topic. Contributors and moderators should review the following lists of resources that have been uploaded to the Dam Safety Toolbox and add links to topic pages as appropriate.
*[[Best Practices Resources Catalog]]
*[[Other Resources Catalog]]
*[[Training Opportunities | Training Catalog]]
*[https://damtoolbox.org/wiki/Category:Example_Pages Example Page Listing]
 
If important references are missing from the website, they should be added to the site as part of the Topic Page creation process and subsequently linked to the Topic Page in accordance with the following:
*[[Guidelines for Creating a Resource Page]]
*[[Guidelines for Creating a Training Page]]
*[[Guidelines for Creating an Example Page]]


----
----
==New Topic Page Template Code==
== New Topic Page Template Code ==
<!-- Code for generic [[Topic Page Template]] -->
The following template code should be copied and pasted into the editor when creating a new Topic Page to facilitate the process of creating, formatting, and reviewing new content. Contributors should add or delete sections, pictures, and code as necessary for a specific topic.


<nowiki><!-- Delete any sections that are not necessary to your topic. Add pictures/sections as needed --> </nowiki></br>
''<nowiki><!-- Default code to remove table of contents and add line break at top of page --></nowiki></br>
<nowiki></nowiki></br>
''<nowiki>__NOTOC__ </nowiki></br>
<nowiki><!-- Remove Table of Contents from page --></nowiki></br>
''<nowiki><!-- Add Category to drive breadcrumb menus --> </nowiki></br>
<nowiki>__NOTOC__ </nowiki></br>
''<nowiki>[[Category:Undefined]] </nowiki></br>
<nowiki></nowiki></br>
''<nowiki>----</nowiki></br>
<nowiki><!-- Add Category to drive breadcrumb menus --> </nowiki></br>
''<nowiki></nowiki></br>
<nowiki>[[Category:<!-- Insert parent category here -->]] </nowiki></br>
''<nowiki><!-- Insert image using {{Picture}} template --></nowiki></br>
<nowiki></nowiki></br>
''<nowiki>{{Picture </nowiki></br>
<nowiki><!-- Add link break between breadcrumbs and page content --></nowiki></br>
''<nowiki><!-- Add image file name (ex.image.jpg) --> </nowiki></br>
<nowiki>----</nowiki></br>
''<nowiki>|image= 1.jpg</nowiki></br>
<nowiki></nowiki></br>
''<nowiki><!--Add link if applicable --> </nowiki></br>
<nowiki><!-- Insert image using {{Picture}} template --></nowiki></br>
''<nowiki>|link= </nowiki></br>
<nowiki>{{Picture </nowiki></br>
''<nowiki><!-- Add picture caption --> </nowiki></br>
<nowiki><!-- Add image file name (ex.image.jpg) --> </nowiki></br>
''<nowiki>|caption= This is a dam.</nowiki></br>
<nowiki>|image= </nowiki></br>
''<nowiki>}} </nowiki></br>
<nowiki><!--Add link if applicable --> </nowiki></br>
''<nowiki></nowiki></br>
<nowiki>|link= </nowiki></br>
''<nowiki><!-- Introductory paragraph or topic page summary --> </nowiki></br>
<nowiki><!-- Add picture caption --> </nowiki></br>
''<nowiki>Paragraph text </nowiki></br>
<nowiki>|caption= </nowiki></br>
''<nowiki></nowiki></br>
<nowiki>}} </nowiki></br>
''<nowiki>== Heading Title == </nowiki></br>
<nowiki></nowiki></br>
''<nowiki>Paragraph text </nowiki></br>
<nowiki><!-- Introductory paragraph or topic page summary --> </nowiki></br>
''<nowiki></nowiki></br>
<nowiki>Paragraph text </nowiki></br>
''<nowiki>== Examples == </nowiki></br>
<nowiki></nowiki></br>
''<nowiki>{{Website Icon}} <!-- Internal Link Format --> [[Page Name | Internal Link Text]] </nowiki></br>
<nowiki>== Heading Title == </nowiki></br>
''<nowiki>{{Website Icon}} <!-- External Link Format --> [ExternalURL Displayed Text] </nowiki></br>
<nowiki>Paragraph text </nowiki></br>
''<nowiki>{{Video Icon}} <!-- Internal Link Format --> [[Page Name | Internal Link Text]] </nowiki></br>
<nowiki></nowiki></br>
''<nowiki>{{Video Icon}} <!-- External Link Format --> [ExternalURL Displayed Text] </nowiki></br>
<nowiki>== Examples == </nowiki></br>
''<nowiki></nowiki></br>
<nowiki>{{Website Icon}} <!-- Internal Link Format --> [[Page Name | Internal Link Text]] </nowiki></br>
''<nowiki><!-- To facilitate updates to the website, do not include the year/date of a reference listed here in the Best Practices Resources section. --></nowiki></br>
<nowiki>{{Website Icon}} <!-- External Link Format --> [External-Link Displayed-Text] </nowiki></br>
''<nowiki>== Best Practices Resources == </nowiki></br>
<nowiki>{{Video Icon}} <!-- Internal Link Format --> [[Page Name | Internal Link Text]] </nowiki></br>
''<nowiki>{{Document Icon}} [[Page Name |  Title, Author]] </nowiki></br>
<nowiki>{{Video Icon}} <!-- External Link Format --> [External-Link Displayed-Text] </nowiki></br>
''<nowiki></nowiki></br>
<nowiki></nowiki></br>
''<nowiki>== Other Resources == </nowiki></br>
<nowiki>== Best Practices Resources == </nowiki></br>
''<nowiki>{{Document Icon}} [[Page Name |  Title, Author]] </nowiki></br>
<nowiki>{{Document Icon}} [[Page Name |  Title, Author, Publication Date]] </nowiki></br>
''<nowiki></nowiki></br>
<nowiki></nowiki></br>
''<nowiki>== Trainings == </nowiki></br>
<nowiki>== Trainings == </nowiki></br>
''<nowiki>{{Website Icon}} <!-- Internal Link Format --> [[Page Name | Internal Link Text]] </nowiki></br>
<nowiki>{{Website Icon}} <!-- Internal Link Format --> [[Page Name | Internal Link Text]] </nowiki></br>
''<nowiki>{{Website Icon}} <!-- External Link Format --> [ExternalURL Displayed Text] </nowiki></br>
<nowiki>{{Website Icon}} <!-- External Link Format --> [External-Link Displayed-Text] </nowiki></br>
''<nowiki>{{Video Icon}} <!-- Internal Link Format --> [[Page Name | Internal Link Text]] </nowiki></br>
<nowiki>{{Video Icon}} <!-- Internal Link Format --> [[Page Name | Internal Link Text]] </nowiki></br>
''<nowiki>{{Video Icon}} <!-- External Link Format --> [ExternalURL Displayed Text] </nowiki></br>
<nowiki>{{Video Icon}} <!-- External Link Format --> [External-Link Displayed-Text] </nowiki></br>
''<nowiki></nowiki></br>
<nowiki></nowiki></br>
''<nowiki><!-- Citations will automatically populate if instructions on the "Guidelines for Inserting a Citation" are followed. --></nowiki></br>  
<nowiki><!-- In the location of an in text citation, simply enclose the citation as follows: <ref name="[reference name]"> citation </ref>. Additional citations for the same source use <ref name="[reference name]"/> at the end of the citation. Citations will automatically populate. Learn more at the Guidelines for Inserting a Citation page or visit https://www.mediawiki.org/wiki/Help:Cite. --></nowiki></br>  
''<nowiki>{{Citations}} </nowiki></br>
<nowiki>{{Citations}} </nowiki></br>
''<nowiki></nowiki></br>
<nowiki></nowiki></br>
''<nowiki><!-- Revision history information --> </nowiki></br>
<nowiki><!-- Revision history information --> </nowiki></br>
''<nowiki>{{revhistinf}} </nowiki></br>''
<nowiki>{{revhistinf}} </nowiki></br>
----
----


<!-- Revision history information -->
<!-- Revision history information -->
{{revhistinf}}
{{revhistinf}}
</noautolinks>

Latest revision as of 05:23, 18 January 2024


Topic pages introduce a topic by providing relevant background information and peer-reviewed guidance. These pages are generally between 100 and 500 words in length. The purpose of these pages is not to document every formula and procedure relating to a topic, but rather to give an overview of the topic and point the user to Best Practices Resources where the topic is addressed in a more comprehensive manner.

Where appropriate, headings should be included to organize and distinguish between subsections of a single Topic Page. If more than a few subsections are needed to convey the information for a single topic page, the creation of new subtopic pages for each of the subsections should be considered. This will help keep Topic Pages concise and focused, thereby increasing the ability to link between subtopic pages and reducing the potential for redundancies in content.

Watch the Dam Safety Toolbox Tutorial: Creating a New Topic Page for additional help.

Naming and Creating a New Topic Page

Care should be taken when naming a new Topic Page. Avoid simplistic titles or terms that can mean multiple things or apply to more than one discipline. Rather, names of Topic Pages should be as specific as possible. For example, if creating a page about the design of relief wells, the page should be called "Design of Relief Wells." If it was simply called "Design", this generic page title may inadvertently auto-link to other pages on the website where the term "design" is used but a link to the very specific topic of relief wells is not appropriate.

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. In cases where similar content or page titles already exist, the existing page should be edited where possible to avoid duplication of content. 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 page 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 topic page. The contributor then simply follows the instructions and template below to complete the creation of the new topic page.

Typical Topic Page Content

At a minimum, a Topic Page will include a page name/title and introductory text (e.g., a definition of a given term). A thoroughly developed Topic Page may include any and all of the following content:

  1. Topic Page Title (see section above regarding the importance of naming a new Topic Page)
  2. Breadcrumb Menu Navigation Links
  3. Introductory Paragraph (typically 100 to 500 words in length)
  4. Pertinent Figures or Images (for demonstrative or aesthetic purposes)
  5. Links to Related Subtopic Pages or Sections with Guidance on Related Subtopics (when content for related subtopics is limited).
  6. List of Examples that illustrate the concepts explained in the previous section(s). These can be links to content on other websites such as ASDSO's DamFailures.org, news articles, videos, etc.
  7. List of Best Practices Resources that are applicable to the topic of interest. Best practices resources are defined as documents that are highly vetted and widely accepted in the dam safety industry (e.g., federal agency documents).
  8. List of Other Resources that are applicable to the topic of interest. Other resources are not as thoroughly vetted as best practices documents, but are still valuable resources for dam safety professionals. Examples include guidance documents and tools developed by state dam safety agencies, landmark technical papers, or academic research.
  9. List of Trainings that are applicable to the topic such as webinars, presentations, etc.
  10. List of Citations (if any) used in the previous sections.
  11. Revision History should be included at the bottom of every page.


Resources, Trainings, and Examples

When creating and updating a Topic Page, it is important to make sure that the content is supported by links to the best resources that are available about that topic. Contributors and moderators should review the following lists of resources that have been uploaded to the Dam Safety Toolbox and add links to topic pages as appropriate.

If important references are missing from the website, they should be added to the site as part of the Topic Page creation process and subsequently linked to the Topic Page in accordance with the following:


New Topic Page Template Code

The following template code should be copied and pasted into the editor when creating a new Topic Page to facilitate the process of creating, formatting, and reviewing new content. Contributors should add or delete sections, pictures, and code as necessary for a specific topic.

<!-- Default code to remove table of contents and add line break at top of page -->
__NOTOC__
<!-- Add Category to drive breadcrumb menus -->
[[Category:Undefined]]
----

<!-- Insert image using {{Picture}} template -->
{{Picture
<!-- Add image file name (ex.image.jpg) -->
|image= 1.jpg
<!--Add link if applicable -->
|link=
<!-- Add picture caption -->
|caption= This is a dam.
}}

<!-- Introductory paragraph or topic page summary -->
Paragraph text

== Heading Title ==
Paragraph text

== Examples ==
{{Website Icon}} <!-- Internal Link Format --> [[Page Name | Internal Link Text]]
{{Website Icon}} <!-- External Link Format --> [ExternalURL Displayed Text]
{{Video Icon}} <!-- Internal Link Format --> [[Page Name | Internal Link Text]]
{{Video Icon}} <!-- External Link Format --> [ExternalURL Displayed Text]

<!-- To facilitate updates to the website, do not include the year/date of a reference listed here in the Best Practices Resources section. -->
== Best Practices Resources ==
{{Document Icon}} [[Page Name | Title, Author]]

== Other Resources ==
{{Document Icon}} [[Page Name | Title, Author]]

== Trainings ==
{{Website Icon}} <!-- Internal Link Format --> [[Page Name | Internal Link Text]]
{{Website Icon}} <!-- External Link Format --> [ExternalURL Displayed Text]
{{Video Icon}} <!-- Internal Link Format --> [[Page Name | Internal Link Text]]
{{Video Icon}} <!-- External Link Format --> [ExternalURL Displayed Text]

<!-- Citations will automatically populate if instructions on the "Guidelines for Inserting a Citation" are followed. -->
{{Citations}}

<!-- Revision history information -->
{{revhistinf}}



Revision ID: 7797
Revision Date: 01/18/2024