Difference between revisions of "Help:Contents"

From TransitWiki
Jump to: navigation, search
(References and footnotes)
(About categories & pages)
Line 1: Line 1:
== About categories & pages ==
+
== Category & Page Relationships ==
=== Relationships ===
 
 
The relationships between categories and pages provide some structure for content in the Wiki, which will be useful as the Wiki matures with more content, or becomes a repository for additional research projects. The typical relationship between categories or categories and pages is a parent-child relationship, although in some instances a page or category will have multiple parents.  A parent is a page or category with at least one child.  A child is a page or category that includes the <nowiki>[[Category:something]]</nowiki> tag.  Below is an explanation of the relationship between different levels of content.
 
The relationships between categories and pages provide some structure for content in the Wiki, which will be useful as the Wiki matures with more content, or becomes a repository for additional research projects. The typical relationship between categories or categories and pages is a parent-child relationship, although in some instances a page or category will have multiple parents.  A parent is a page or category with at least one child.  A child is a page or category that includes the <nowiki>[[Category:something]]</nowiki> tag.  Below is an explanation of the relationship between different levels of content.
 
# ''Group of categories'' (eg: [[:Category:Internal strategies]], [[:Category:External strategies]]).  These are top-level groupings, and for this project these categories have no parents.  This level can be thought of as Parts of a report.
 
# ''Group of categories'' (eg: [[:Category:Internal strategies]], [[:Category:External strategies]]).  These are top-level groupings, and for this project these categories have no parents.  This level can be thought of as Parts of a report.
Line 12: Line 11:
 
# ''Sub-page'' - When some content provided on a ''strategy'' page would be too narrowly-focused or detailed for the typical reader, this additional information should be linked in a sub-page.  A ''sub-page'' differs from a ''strategy'' page in that it is not a strategy in-and-of itself (and therefore does not have a <nowiki>[[category:whatever]]</nowiki> tag, and it usually only linked by a parent page.
 
# ''Sub-page'' - When some content provided on a ''strategy'' page would be too narrowly-focused or detailed for the typical reader, this additional information should be linked in a sub-page.  A ''sub-page'' differs from a ''strategy'' page in that it is not a strategy in-and-of itself (and therefore does not have a <nowiki>[[category:whatever]]</nowiki> tag, and it usually only linked by a parent page.
  
=== Content ===
+
== Page content ==
 +
=== Page titles ===
 +
Page titles should describe strategies, measures, or concepts as clearly and accurately as possible
 +
please:
 +
* use active voice
 +
* use simple language
 +
* avoid prepositions
 +
* avoid redundancy when possible (eg: transit, bus, rail)
 +
=== Page structure ===
 
Each page should have an introduction to the concept, examples of how the concept advances desired outcomes, and at least one link to further reading.  The minimum length of a mature page should be 10 lines or longer.  Any mature page not meeting these criteria is considered a "stub" and should be rolled up into its parent.
 
Each page should have an introduction to the concept, examples of how the concept advances desired outcomes, and at least one link to further reading.  The minimum length of a mature page should be 10 lines or longer.  Any mature page not meeting these criteria is considered a "stub" and should be rolled up into its parent.
  
 +
=== Further reading ===
 +
Always include a link and short abstract that helps the reader answer the question "should I follow this link?".  A major feature of this wiki is that it can facilitate the identification of cost effective strategies that are appropriate to an agency, and connect agency staff with the additional information they need to explore and implement the strategy.
 
==== Citation format ====
 
==== Citation format ====
 
Citations, references, and links to further reading should take the form:
 
Citations, references, and links to further reading should take the form:
 
<code>Author or Institution Name. "Publication Title." Year of Publication</code>
 
<code>Author or Institution Name. "Publication Title." Year of Publication</code>
==== Further reading ====
+
=== References and footnotes ===
Always include a link and short abstract that helps the reader answer the question "should I follow this link?".  A major feature of this wiki is that it can facilitate the identification of cost effective strategies that are appropriate to an agency, and connect agency staff with the additional information they need to explore and implement the strategy.
 
==== References and footnotes ====
 
 
Occasionally you will want to cite statements made in pages. Any in-line citation should use the the following code to produce a footnote citing a specific source:
 
Occasionally you will want to cite statements made in pages. Any in-line citation should use the the following code to produce a footnote citing a specific source:
 
<code><nowiki><ref>[http://linkurl.com/example Author or Institution Name. "Publication Title." Year of Publication.]</ref></nowiki></code>
 
<code><nowiki><ref>[http://linkurl.com/example Author or Institution Name. "Publication Title." Year of Publication.]</ref></nowiki></code>
Line 27: Line 34:
 
Produce a list of footnotes using the <code><nowiki><refrences /></nowiki></code> tag at the bottom of the page under a </nowiki>== Notes ==  section. </nowiki>.
 
Produce a list of footnotes using the <code><nowiki><refrences /></nowiki></code> tag at the bottom of the page under a </nowiki>== Notes ==  section. </nowiki>.
  
==== Images ====
+
=== Images ===
 
this
 
this
  
 
=== Category titles ===
 
=== Category titles ===
 
Juan has created titles from the outline following the above relationship rules.  You shouldn't need to create a new category.  Should you need to, please coordinate with Juan by email.
 
Juan has created titles from the outline following the above relationship rules.  You shouldn't need to create a new category.  Should you need to, please coordinate with Juan by email.
 
=== Page titles ===
 
Page titles should describe strategies, measures, or concepts as clearly and accurately as possible
 
please:
 
* use active voice
 
* use simple language
 
* avoid prepositions
 
* avoid redundancy when possible (eg: transit, bus, rail)
 

Revision as of 19:50, 14 February 2012

Category & Page Relationships

The relationships between categories and pages provide some structure for content in the Wiki, which will be useful as the Wiki matures with more content, or becomes a repository for additional research projects. The typical relationship between categories or categories and pages is a parent-child relationship, although in some instances a page or category will have multiple parents. A parent is a page or category with at least one child. A child is a page or category that includes the [[Category:something]] tag. Below is an explanation of the relationship between different levels of content.

  1. Group of categories (eg: Category:Internal strategies, Category:External strategies). These are top-level groupings, and for this project these categories have no parents. This level can be thought of as Parts of a report.
  2. Category - items at this second level have a parent (a level 1 group of categories) and at least two "children" outcome (eg: Operations planning)
  3. Outcome or result is a category that describes a desired outcome for which a transit agency would employ strategies. Content at this level has at least one parent and two children. While content at this level will usually take the form of a category, it can take the form of a page if the content for none of the children strategies is (or is anticipated to be) long enough to warrant its own strategy page.
  4. Strategy - a strategy usually takes the form of a page. This page includes:
    1. an introduction to the concept covered in the page that gives the intelligent but unfamiliar reader context
    2. an overview of the benefits and drawbacks involved with pursuing the strategy, including how the strategy can help an agency in pursuit of any desired parent outcome or result , but also any adverse effects the strategy may have on other strategies, aspects of transit service delivery, or stakeholders
    3. examples of the strategy in action
    4. further reading for those interested in learning more, including academic literature and case studies, with link to content or DOI/library page. Each item linked in further reading should include at a minimum of two sentences that inform the reader's decision to follow or not follow the link.
  5. Sub-page - When some content provided on a strategy page would be too narrowly-focused or detailed for the typical reader, this additional information should be linked in a sub-page. A sub-page differs from a strategy page in that it is not a strategy in-and-of itself (and therefore does not have a [[category:whatever]] tag, and it usually only linked by a parent page.

Page content

Page titles

Page titles should describe strategies, measures, or concepts as clearly and accurately as possible please:

  • use active voice
  • use simple language
  • avoid prepositions
  • avoid redundancy when possible (eg: transit, bus, rail)

Page structure

Each page should have an introduction to the concept, examples of how the concept advances desired outcomes, and at least one link to further reading. The minimum length of a mature page should be 10 lines or longer. Any mature page not meeting these criteria is considered a "stub" and should be rolled up into its parent.

Further reading

Always include a link and short abstract that helps the reader answer the question "should I follow this link?". A major feature of this wiki is that it can facilitate the identification of cost effective strategies that are appropriate to an agency, and connect agency staff with the additional information they need to explore and implement the strategy.

Citation format

Citations, references, and links to further reading should take the form: Author or Institution Name. "Publication Title." Year of Publication

References and footnotes

Occasionally you will want to cite statements made in pages. Any in-line citation should use the the following code to produce a footnote citing a specific source: <ref>[http://linkurl.com/example Author or Institution Name. "Publication Title." Year of Publication.]</ref> Alternatively, one can produce a text-only footnote by omitting the link code brackets <ref>example footnote</ref>.

Produce a list of footnotes using the <refrences /> tag at the bottom of the page under a </nowiki>== Notes == section. </nowiki>.

Images

this

Category titles

Juan has created titles from the outline following the above relationship rules. You shouldn't need to create a new category. Should you need to, please coordinate with Juan by email.