Advice for using Foswiki

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

General advice

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.

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:

Modify structure

If a page appears ill-structured, feel obliged to greatly reorganize it in order to make it more easily understandable and maintainable: Make sure you understand the purpose of the page before, so that your judgement will not be mislead.

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.