From DPWiki
Jump to navigation Jump to search

Working with jargon-related content

If you'd like to create jargon-related pages which follow the structure that has been used up to this point, or if you want to use existing definition page content in other articles in DP Wiki, see the detailed directions given below.

If you think the transclusion technique described in these instructions and suggestions is a bit beyond your "comfort level," you can type up your definition and send it to kraester in a PM, and she will take care of integrating it into the current Jargon scheme, or, of course, you can just "do your own thing," and set the page up any way you would like to. :) UPDATE: I'm sorry to say that because of some serious health issues kraester is no longer an active participant in DP activities.

Jargon Guides

Creating the "definition pages"

Names of "definition pages"

When creating definition pages, try to give them short simple names, which are likely to be words that would be used by someone using a keyword search to find information in DP Wiki.

If the "most obvious" term name is already used by an existing page, that's fabulous! A "definition page" for a term or subject should "serve," not supplant, the information that someone has already created about a subject, as well as serving the needs of someone who is just learning the general jargon surrounding DP.

Take a look at the existing page to see if there is a paragraph or two that serves as a short definition for the term (as would be found in a dictionary, for instance). If there is, the best approach is to pull that definition out of the main subject page and put it on the separate definition page. So far in situations like this, we've been using page names like "SubjectName definition" for the definition pages.

Once the definition page has been created, you can put a call to it on the main subject page (as well as on any desired Jargon Guide pages), as is discussed in this article's transcluding the definitions section. Once again, one of the "beauties" of this approach to jargon-related content is this ability to use a consistent definition in a wide variety of pages, with the information only having to be entered and updated in one location (on the "definition page" itself).

For examples of this type of interrelationship among pages, see DPCustomMono and DPCustomMono definition, LaTeX and LaTeX definition, and Page Details and Page Details definition.

An exception to the "use transclusion to call definition in from definition page to larger article" technique is when the "larger article" is one that is designed to eventually become "official documentation," such as the Project Managing FAQ, Post-Processing FAQ, etc. In those kinds of cases, the actual text should be left on the FAQ/documentation page, and a separate, independent definition page can be created to transclude into other non-documentation-oriented articles, such as was done with the Copyright clearance definition page and the more detailed Copyright clearance section of the CP FAQ.

Structure of "definition pages"

Individual jargon-definition pages should usually have the following structure/layout:

  <noinclude><!--This page likely transcludes into other pages.  You can see a list of 
  'destination pages' for this content by clicking on the 'What links here' link at the left. 
  If you want to ADD content instead of just modifying this basic definition, you may want 
  to make your changes to one of those pages instead of this one, or surround your additions 
  with "noinclude" tags so it doesn't transclude awkwardly into those 'destination' pages.-->
  {{Jargon Navigator}}</noinclude>
  definition text

The <!-- comment --> informs page editors that, unlike most other Wiki articles, changes made to this page will likely affect other pages as well. (It wouldn't hurt anything to copy the comment's text onto the article's associated Talk page too.)

The {{Jargon Navigator}} code calls in the Jargon Guides' navigation box Template (shown above, to the right of this page's TOC). The template call MUST be enclosed in <noinclude> tags so the Jargon Navigator does not transclude into any "destination" pages. (If you do want the Jargon Navigator to be shown on any "destination" pages, insert it on that page itself.)

It is best to avoid blank lines except within the definition text itself. (Any blank lines outside the "noinclude" markup will transclude to "destination" pages and any blank lines inside the "noinclude" markup will affect the line spacing on the "definition" page itself.)

The text on an individual jargon-definition page should be no longer than one screen (and will usually be much less than one screen). It is best to use complete sentences when creating the definition text, and to include the term itself in the definition's first sentence, if at all possible. Remember that these "definition pages" are designed primarily to transclude into other pages; thus, the definition is very likely to have to be able to "stand on its own," without the definition-page's name, which serves as a heading on the definition-page itself.

In addition to specifying the Jargon Category, you can add any other Category specifications you feel appropriate, but all of the Category codes should be enclosed in <noinclude> tags to preclude the categories being transcluded to any "destination" pages. (You should specify destination pages' categories in those pages themselves.) You can choose from one of the previously used Categories, or create a new one.

Transcluding the definitions to "destination" pages

Once a definition page has been created, its text can be transcluded to any other page in the wiki by simply inserting a call on the "destination" page. A call is created like an interlink, you just use {{braces}} instead of [[brackets]].

  • If the transclusion source page is stored in the Template namespace, you just surround the template name with the braces, as in the {{Jargon Navigator}} template call.
  • If the transclusion source (definition) page is stored in the Main namespace, you must precede the page name with a colon (:) within the braces: e.g., {{:PageName}}. [This is way the vast majority of the defintion pages and calls are currently set up.]
  • If the transclusion source (definition) page is stored in any namespace other than Template or Main, you must include the namespace name in the call. For example, {{XXXX:PageName}} will call in information found on the PageName page in the XXXX namespace. [So far, very few definition pages have been created in any namespaces other than Main or Template.]

When creating calls, be sure to watch the punctuation and case of letters in page names. After the first letter, page names are case-sensitive. While DP Wiki's Search utility is a tad forgiving when it comes to punctuation and case differences, calls are quite punctuation- and case-dependent. For example, calls of {{Smooth-reading}} and {{Smooth Reading}} will not produce any results when the page you are trying to pull information from is actually named Smooth-Reading.

Facilitating user-friendly searches

As was mentioned earlier, it is best to name individual definition pages with short, simple names, which are terms that people are likely to use in keyword searches for information. If you can think of alternative likely search words, you can create stub pages for each likely keyword that re-directs to that concept's main definition page, or to an existing, more general, page about the subject, as you think is appropriate.

Also don't forget about terms that can be singular or plural, or use alternative spelling/punctuation/letter case. For example, "round" and "rounds" are two different words which could lead to two different pages, as are "Smooth-Reading" and "Smooth Reading."

A "redirect" page is especially handy if the term is known by an acronym. A page with the name of the acronym should be created and set to re-direct to a page named with the spelled-out term, and which holds the actual definition of the term.

The contents of the alternative search term/acronym pages should follow this model:

  #REDIRECT [[PageName]]


With the pages for all the different names that may be applied to a term being redirected to one canonical definition or subject page, it is useful/handy/prudent if the text of the definition make references (but not links) to any appropriate acronyms and alternative names for the concept. For an example of this, see the Smoothing-Reading definition shown below.

A Transclusion Example

Canonical definition page for Smooth-Reading concept

Article name: Smooth-Reading

  <noinclude><!--This page transcludes into other pages.  You can see a list of 
  'destination pages' for this content by clicking on the 'What links here' link at the left. 
  If you want to ADD content instead of just modifying this basic definition, you may want 
  to make your changes to one of those pages instead of this one, or surround your additions 
  with "noinclude" tags so it doesn't transclude awkwardly into those 'destination' pages.-->
  {{Jargon Navigator}}</noinclude>
  The goal of '''S'''mooth-'''R'''eading ('''''SR''''') is to read the  
  [[Post-Processing|post-processed]] text attentively, as for pleasure, with just a little
  more attention than usual to punctuation, etc. This is NOT full scale [[proofreading]], and 
  comparison with the [[project|project's]] scans is not needed. Just read it as your normal,
  sensitized-to-proofing-errors self, and report any problem that disrupts the sense or the 
  flow of the book.  

  Also, one who does smooth-reading (also ''smoothie'', or rarely, ''SRer'').

  For more information, see the [[Smooth-reading FAQ]].
  [[Category: Post Processing]]</noinclude>

Section on Jargon Guide showing call to Smooth-Reading definition

  ===SR: Smooth-Reading===

Example of acronym page redirecting to canonical definition page

Article name: SR

  #REDIRECT [[Smooth-Reading]]


Examples of alternative terms' pages redirecting to canonical definition page

Article name: Smoothie

  #REDIRECT [[Smooth-Reading]]


Article name: Smooth Reading

  #REDIRECT [[Smooth-Reading]]


As you can see, a copy-and-paste can come in very handy when creating these types of re-direct pages. :)