Advice for using Foswiki

A number of norms and hints for how to best use this Wiki platform.

General advice

• Subscribe to WebNotify in all webs relevant to you to stay informed of what goes on there.
• Correct small mistakes (if obvious) and omissions on other people's pages whenever you find them. This small-scale collaboration is what makes Wikis so powerful.
• Read the CompleteDocumentation, e.g. about the WikiSyntax notation, System.Macros (in particular TOC and SEARCH), or the icon shortcuts.
• Think.

When creating new pages

Topic name

Since there are no directories within a web, there is big danger of cluttering the web over time with obsolete pages using confusing names.

• Thus, where possible, pages should use naming conventions for indicating the type of material on them, typically in the form of fixed prefixes (e.g. Seminar, Vorlesung, Project, etc.) or suffixes (e.g. Rules, Home, 2004, 2005, etc.).
  • This becomes very important once the number of pages in a web grows large: Since there are no directories, structure must be imposed by naming rules.
• Pages belonging together should share a common name prefix (or suffix).
• The language used for the name should normally indicate the language used in the content of a page. There may be exceptions when no good name in that language can be found or when it would break a naming convention.

Parent

To find where a page belongs, another Foswiki feature comes handy: Each page has a parent. Manually setting parents is cumbersome, though. Therefore, always place a link to a page first and then create the page by following the link. The page containint the link will automatically be set as the parent.

Structure/headings

If the page is one of a number of similar ones (e.g. one of several course pages for Seminar courses), use the same structure as on an existing page if possible. Structure should be different only if there is good reason for it.

One can also prepare templates for various kinds of pages and automatically use those during creation by creating pages via simple forms. See DataForms for examples.

How many topics?

To avoid cluttering the web with topics, it is typically preferable to have one larger page rather than many small ones for any one purpose. When using many headings and the %TOC% feature, you even get a lot of hyperlinks for free. Printing also tends to become easier that way.

One should also avoid creating short-lived pages that will turn into garbage soon. Rather, such content should be added to existing pages where possible.

Structured content: Forms

To make more structured data management possible, consider adding a Form to your page. You can think of a form as a single database record. Each Foswiki topic can carry a form besides its text content, so that a number of pages together make up something similar to a relational database table.

Logically, that is usually useful only if all instances of a certain kind of page have the same kind of form. See DataForms for details.

The DataForms allows treating ordinary tables as forms as well, so that a page can even have more than just one form if necessary. It supports more powerful querying operations on forms as well. Example: Creating applications with DataForms

When modifying existing pages

Preserve structure

When you add to existing content, make sure you preserve the original design ideas of the page's structure:

• Add new material in the appropriate place.
• If there is no appropriate place, create one (i.e. a new heading) in the appropriate region.
• Avoid redundancy.
• Repair any existing structural defects that you find.

Modify structure

If a page appears ill-structured, feel obliged to greatly reorganize it in order to make it more easily understandable and maintainable:

• Remove, reorder and insert new sections as required
• Move material between sections as required
• Remove redundancy
• Correct mistakes and improve formulations where possible.
• Kick out irrelevant material.

Make sure you understand the purpose of the page before, so that your judgement will not be mislead.

Add hyperlinks

When modifying a page, always try to insert at least one additional hyperlink in the existing part of the page by replacing plain text with an appropriate WikiWord or adding links using the [[][]] notation.

This greatly improves the navigatability of the web over time.

Managing topics as a whole

You can and should rename or delete a topic if need be. WikiWord links to the topic will automatically be corrected when renaming. See ManagingTopics.

(Comments)

If you have comments or additions but do not want to include them in the main body above, add them here and sign as indicated below the text window.