Guidelines for Creating a Topic Page: Difference between revisions
No edit summary |
Rmanwaring (talk | contribs) No edit summary |
||
| Line 2: | Line 2: | ||
[[Category: Dam Safety Toolbox Formatting/Style Guide]] | [[Category: Dam Safety Toolbox Formatting/Style Guide]] | ||
---- | ---- | ||
<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 | <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. | ||
Where appropriate, headings should be included to organize and distinguish between subsections of a single | 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. | ||
==Naming a New Topic Page== | == Naming a New Topic Page == | ||
Care should be taken when naming a new | 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. | ||
==Typical Topic Page Content== | == Typical Topic Page Content == | ||
At a minimum, a | 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: | ||
# '''Topic Page Title''' (see section above regarding the importance of naming a new topic page) | # '''Topic Page Title''' (see section above regarding the importance of naming a new topic page) | ||
| Line 53: | Line 53: | ||
---- | ---- | ||
==New Topic Page Template Code== | == New Topic Page Template Code == | ||
The following template code should be copied and pasted into the editor when creating a new | 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. Users should add or delete sections, pictures, and code as necessary for a specific topic. | ||
''<nowiki><!-- Default code to remove table of contents and add line break at top of page --></nowiki></br> | ''<nowiki><!-- Default code to remove table of contents and add line break at top of page --></nowiki></br> | ||
Revision as of 23:10, 23 December 2022
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.
Naming 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.
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:
- Topic Page Title (see section above regarding the importance of naming a new topic page)
- Breadcrumb Menu Navigation Links
- Introductory Paragraph (typically 100 to 500 words in length)
- Pertinent Figures or Images (for demonstrative or aesthetic purposes)
- Links to Related Subtopic Pages or Sections with Guidance on Related Subtopics (when content for related subtopics is limited).
- 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.
- List of Best Practices Resources that are applicable to the topic of interest.
- List of Trainings that are applicable to the topic such as webinars, presentations, etc.
- List of Citations (if any) used in the previous sections.
- Revision History should be included at the bottom of every page.
Best Practices 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 editors 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:
- Guidelines for Creating a Best Practices Resource Page
- Guidelines for Creating a Training Page
- Guidelines for Creating an Example Page
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. Users 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]
== Best Practices 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: 6421
Revision Date: 12/23/2022