Help:What is the Wiki and How is it Used

From ISFDB
Jump to navigation Jump to search

(This page is a work in progress. I will be returning to it shortly. -DES Talk 03:25, 11 November 2008 (UTC)) (No he won't, but I'll be trying to organize it) ../Doug H 16:35, 2 December 2021 (EST)

This page is intended to describe the basic nature and features of the Wiki section of the ISFDB. It should serve as a general introduction to wikis for people not accustomed to using or editing a wiki and to describe how ISFDB has organized its wiki.

What is a Wiki?

A wiki is intended to support collaborative work in a quick and simple manner. ("Wiki" is a Hawaiian word for "fast".) A wiki appears as a set of linked web pages and provides tools allowing users to navigate and update those pages directly through their web browser. ISFDB uses its wiki for documentation and collaboration. There are many other wikis, both public and private, using various implementations of the wiki concept. The ISFDB uses the MediaWiki software, which is the same software used by Wikipedia.

A wiki page is defined by its name. The wiki software will retrieve, format and present a page when a request is made for that page. The user has the option of modifying the text that defines the page. If the user choses to edit the page, they are presented with a standard edit page with the text for the named page presented in an edit box. Only text is allowed, no links, images, formatting or layout are entered. To provide these features, a set of formatting commands can be included in the text. These commands are part of a markup language particular to the wiki software. ISFDB uses wikitext. The use of wikitext is optional for any page, but essentially all pages use some.

The three main types of commands in wikitext are concerned with formatting (titles, indentation, bullets, bold), linking (to wiki pages or external pages) and including other text (functions, templates). These commands are generally delimited by brackets [ ], braces { }, multiple single quotes '' '' or equal signs == ==. Details can be seen on the Help:Wikitext page.

Links are created when a wiki page name is included inside brackets in the text for a page (e.g. [[Help:FAQ]]). When the wiki presents the page, the link will be highlighted and underlined. If the page does not exist, it will be displayed in red. Following the link will bring up a default page explaining that there is no text. The user has the option of creating the text that defines the page. In this forward generation paradigm, users control the content of the pages and the interconnections between the pages.

The following discussion refers to the ISFDB's MediaWiki-based wiki.

Editing wiki pages

On the ISFDB wiki (unlike some other wikis) no one can make any edit without being logged in.

To edit any wiki page, simply click the "edit" tab at the top of the page. The display will enter edit mode, and the wiki text will be shown in an edit box. Make whatever additions or changes you wish, fill in the "summary" box below the edit box with a brief description of the nature or purpose of the edit (the "Edit summary", and click "save page" when you are done. Your changes are promptly saved to the wiki.

More often, it is helpful to edit only a section of a wiki page. Each section header has an "edit" link to the right. Clicking on this link will edit the section that starts with the header, including and sub-sections it may contain. This works exactly like editing an entire page, except that only the wiki text for the section (including the header) is in the edit box, and only the section will be changed by the edit. The Summary will be pre-filled with "/* Section Name */. Enter your summary of the edit after the pre-filled summary. If you changed the section name in your edit, change the pre-filled name also, please. If you added a new section, you should replace the pre-filled section name with the new name. This will allow the automatically created links on history and changes pages to work properly.

While editing, it is often helpful to click the "Show Preview" button at the bottom of the page, next to the "save changes" button. This shows how the edited page will be rendered, without saving any changes. This display is called a preview.

For more on editing wiki pagfes, see Help:Editing

Primary and "talk" pages

Wiki pages are organized in pairs. One page is the "primary" page intended for presenting material and the second is a "talk" page intended for users to discuss the primary page material. At the top of each wiki page are several tabs. The first (from the left) is for the primary page, and will say "page" (or "help page" or "project page" or "user page" or some similar variant depending on the namespace, described below)). The second is labelled discussion. Selecting either tab will take you to the display for that page. The page you are on will be highlighted.

The general convention is that a talk page is used to discuss the primary page, what should go on it, how it should be organized, etc. The purpose of the primary page varies, depending on the particular page involved. In some cases the term "discussion" may be in red. That indicates that the particular page has not had its talk page created yet -- but anyone can create it at any time.

Note also that on talk pages, and primary pages that are for the discussion of topics, users generally write in the first person and sign their comments. On primary pages that are basically descriptive, users write impersonally, and text is not usually signed.

User pages and User talk pages

A special case is the "User" page. This is a page that describes a particular user of the project, or that user's current activity, to do lists, or such things. Such pages have names that start with "User:" followed by the user's UserID on the wiki. For example User:Alvonruff or User:DESiegel60. Every registered user has a user page available, although some users may not have chosen to create their user pages. Normally, a user page will be edited only by the user it is for.

The corresponding talk page, the "user talk" page, has a name that starts "User talk:" followed by the user ID. This page is used, not for discussing what should go on the user page, but for communicating with the user in question. Whenever a user displays a wikipage, if there have been changes to that user's talk page, there will be a banner to notify the user that he or she has new messages. (of course this occurs only if the user is logged in). The user can click on the link in the banner and be taken to his or her user talk page. Also, there is a link to the talk page, called "my talk" at the top of every wiki page, in small type.

Conventions on the use of user talk pages differ on different wikis. On the ISFDB wiki, the convention is that a user responds to a message on the same page where the original message was posted, and it is the responsibility of the poster to watch or check that page to see the response. This keeps a discussion together.

In all discussions on this wiki, the convention is that responses are indented relative to the text being responded to. This is done by starting a paragraph with one or more colors, one for each indent level wanted. These display as indents. Do not start text paragraphs with tabs or blank spaces. This causes an unwrapped fixed-font display, which is generally unhelpful in such situations, although it can be useful for special purposes.


Namespaces

Wiki pages are organized into various namespaces. Every page belongs to one and only one namespace. Namespaces are used to separate wiki pages by purpose or function. Several wiki display functions, such as the one at this page, can select only the pages in a particular namespace. Notably, the Advanced Search function allows you to specify which Namespaces are to be searched. Some namespaces display differently or offer specialized functionality.

Namespaces are assigned to a page based on the page's name. A namespace and a colon (:) are prefixed to the name of the wiki page. For example, this page is in the "Help:" namespace. Putting a name and colon at the beginning of a wiki page name does not create a namespace. The list of available namespaces is set up as part of the wiki site configuration. Only people with developer-level access to the ISFDB site can add (or remove) a namespace.

Different wikis have different sets of namespaces, according to their needs. On the ISFDB wiki, the current namespaces are:

Prefix Talk prefix Purpose
<blank> Talk: Main namespace, mostly used for lists (such as Magazines, for the Main Page, for consistancy project pages and other bibliographic project pages, and for documenting the ISFDB database structure
Help: Help talk: For pages that document the use of the ISFDB database or of the wiki
User: User talk: For pages assigned to registered users of the wiki
ISFDB: ISFDB talk: For pages about how the ISFDB is or should be organized, for discussion of procedures and policies
Image: Image talk: For stored pictures. See Help:How to upload images to the ISFDB wiki
MediaWiki: MediaWiki talk: Internal systems oriented. These aren't the droids you're looking for.
Template: Template talk: For wiki-based text, used as boilerplate or macros.
Category: Category talk: For category pages generated by automatic and manual means.
Special: For lists generated by the wiki software. There is no text associated with this namespace.

The following namespaces were used in the past but are in the process of being migrated to the Note fields of ISFDB records. If a Web page in one of these namespaces is to large to migrate to a Note field, it should be linked from the affected ISFDB record as a third party URL:

Prefix Talk prefix Purpose
Author: Author talk: For bibliographic notes on the work of a particular author, and for discussions on the best way to deal with db entries on that author's work
Bio: Bio talk: For brief, factual, biographical sketches of specific authors, mostly ones that do not have Wikipedia articles. See ISFDB:Policy#Biography Policy.
Magazine: Magazine talk: For bibliographic notes on the issues of a particular magazine, and for discussions on the best way to deal with db entries involving that magazine.
Fanzine: Fanzine talk: For bibliographic notes on the issues of a particular fanzine, and for discussions on the best way to deal with db entries involving that fanzine.
Publisher: Publisher talk: For bibliographic and historical notes on a particular publisher, imprint, or other business entity involved in publishing SF.
Publication: Publication talk: For bibliographic notes on a particular publication, and for discussions on the best way to deal with its db entry.
Series: Series talk: For bibliographic and organizational notes on a particular series, and for discussions on the best way to deal with db entries involving that series.

The following prefixes have been used, but do represent Namespaces. They are in the Main Namespace.

DisplayBug:, EditBug:, Feature:, ObjectClass:, Reference:, Requirements:, Schema: and XML:

Similarly, the nesting of colons in other Namespaces (e.g. Template:AuthorFields:BirthDate) refers to pages with a colon (e.g. AuthorFields:Birthdate) in the prefixed Namespace.

Categories

Like Namespaces, Categories are an indexing wiki feature used to organize pages. A wiki Category is a page in the Category Namespace that may or may not have saved text. A page becomes part of a Category when it includes a reference to that Category, e.g. [[Category:Fish]]. When the page is displayed, it will have at its bottom, a box providing a list of links to the Categories the page belongs to. And yes, a page can belong to multiple Categories.

The wiki page for a Category will list all of the pages that belong to it, in alphabetical order. And because it is just another wiki page, explanatory text may be saved that will be displayed above the page list. And because it is just another wiki page, it can reference other Categories, making it a sub-Category. A page's sub-Categories are listed automatically above the page list. The top level Category is Category:Categories.

Links

Wiki-links

You can insert a link to another wiki page by surrounding the name of the page with paired brackets. For example, a link to the "Magazines" page would be entered like this:

[[Magazines]]

and would display like this:

Magazines

A link to a page in a namespace (other than main) includes the namespace in the link. for example, a link to the page "How to verify data" in the Help namespace would be entered like this:

[[Help:How to verify data]]

and would display like this:

Help: How to verify data

You can change the displayed text of a link. For example if a link is entered like this:

[[ISFDB:Policy|the policy page]]

it will look like this:

the policy page

Links can be used in the middle of a section of text like this, whenever they are appropriate.

Links to pages in the category and image namespaces are special. A "link" to a category page puts the page linked from into that category. A "link" to an image page displays the image where the links is. To link to a category without putting the page into the category, start the link with a colon. Enter the link [[:Category:Wiki Help]] to get the link Category:Wiki Help. To link to an image page without displaying the image, also precede the page name with a colon. Enter the link [[:Image:Bheleu-Tweddell.jpg]] to get the link Image:Bheleu-Tweddell.jpg.

External links

You can also link to an external site, by enclosing the URL in single square brackets. For example, if you enter:

[http://www.amazon.com/] 

a link to the US Amazon main page will display like this

[1]

Instead, you can specify the link text by including it after a space. For example, if you enter:

[http://www.amazon.com/ Amazon US] 

You will display:

Amazon US

This technique can be used to link to any web page with a URL, including history displays and other special features on the wiki, that cannot be linked to with a wiki link. However, wiki-links should be used rather than external links when possible. It is more efficient, and it enables backlinks.

Templates

Pages on the wiki can use templates. Templates are special pages that contain test or wiki markup that can be inserted into other pages. Some Templates are simple boilerplate, that always produce the same output. Others take parameters (arguments) that are used in ways more or less complex to create the tempalte's output.

A template is called ("transcluded") by placing iits name in double curly braces. For example, the template "LOC" is called like this:

{{LOC}}

which results in this:

Library of Congress Online Catalog

When parameters are used, they are marked off by vertical bars. For example, the template A (link to author record) takes one required and one optional parameter. It might be called as:

{{A|Isaac Asimov}}

or as

{{A|Isaac Asimov|Asimov's database record}}

This would led to the following results:

Isaac Asimov or database record Isaac Asimov

Some templates use named parameters. These are specified by the name of the parameter, followed by an equals sign, and the value being assigned. For example, the template {{Cover Image Data}} uses several named parameters. See its template page for detaiuls and examples.

Templates are normally pages in the Template: namespace. A template page, besides including the actual template text and markup, generally displays or links to documentation of the template including a list of the paramaters (if any) and their names and reasonable values. The corresponding Template talk: page may contain discussion of how a template should be used, or of how it might be altered or improved.

See Help:Template for more on templates generally.

The following templates can be useful on the ISFDB wiki.

Template Name & Link Brief description
{{P}} Links to a Publication record in the database
{{T}} Links to a Title record in the database
{{A}} Links to a Author record in the database
{{Cover Image Data}} Identification and License data for a cover image
{{Cover Image Data2}} Shorter and simpler form of Cover Image Data
{{C}} Alias for Cover Image Data2
{{Cover Image Data3}} Shorter and simpler form of Cover Image Data, but adds artist name to what Cover Image Data2 does
{{C3}} Alias for Cover Image Data3
{{Logo Image Data}} Identification and License data for a Logo image
{{Sig Image Data}} Identification and License data for an image of an artist's signature

For further information and a fuller list, see