• View
• Edit
• History
• Attach
• Print
• Backlinks

AdminHints

Questions answered by this recipe

• What hints or suggestions can you give me as I begin administrating a new wiki?

Description

Hints & suggestions for wiki administrators.

Notes

Make one change at a time

If you were a scientist, a mainstay of your scientific method would be to ensure that you have only a single variable in your experiment at a time. In wiki administration it is essential that you make one change at a time.

1. Start with a known, working state (test it to make sure it works!)
2. Choose a single feature to install or enable
3. Read the instructions carefully and follow the instructions exactly
4. Test your single change. If it doesn't work go back to step #3 and re-read and check carefully
5. Once you are confident that this single change works and has not caused other, undesired side-effects, you have a new "known, working site" from step #1 and you can go back and implement one more change.

Backup regularly, keeping a history

Before you start making changes (and/or after you finish making changes and have tested things), make a backup of your site configuration.

Refer to cookbook recipes such as BackupPages or WbBackup for a full, formal approach to backup.

The "poor man's approach" to backing up your wiki configuration before making changes is simply to make a copy of your configuration files in your wiki's local/ directory.

Normally this consists of copying config.php to config.php.YYYY-MM-DD. This means that you can look in that directory and see a list of dated "known states" that you can go back to. Thus if you suddenly notice that something is not working, you copy off your CURRENT (non-working) config.php somewhere, and copy back the most recent known state. If it still doesn't work then you go back to a previous version, continuing on until you find when the problem was introduced. Then you can compare the differences between the last-working-state config.php and the first-broken-state config.php and see exactly what changed.

The same applies to any wiki-group or -page specific configuration files in your local/ directory you may have added.

Write down your changes in a central location

Whether you choose a physical notebook in which to write things down or whether you choose a directory in your personal computer to store a series of text/Word documents -- choose some place to write down what changes you are making.

Add comments to your additions and changes in config.php by using text starting with hashes # or double slashes //, as you can see used widely in docs/sample-config.php

I know, it increases the amount of work. I know, it makes it take longer. But if you will discipline yourself to writing down the reason why you are making a change and what the actual change is (including that little change that seems irrelevant -- maybe especially that one!) then you will find that your initial "extra" work actually saves you time in the long term.

Reporting problems and asking for help

• Don't hesitate to ask for help, but remember that the help you are getting is from volunteers who are gifting you with their time.
  • Make sure you have done your homework thoroughly
  • Never assume/presume that someone should help you -- be courteous in the way you ask for help
• If you have an error message, be specific. Don't say "I got a bunch of errors" but quote them exactly, word-for-word
• Describe recent changes and the steps you followed to see the errors/problems as fully as you can. If you made a change a few days ago don't assume it is irrelevant -- let people know you've been working on an upgrade or working on installing a new recipe.

How to ask for help

• Read PmWiki's help pages on Installation and Initial Setup Tasks.
• Read PmWiki's general Questions & Answers page.
• Read the Q&A section or -Talk page of a specific recipe.
• Post a recipe specific question on its -Talk page.
  • Some recipe authors monitor talk pages, others don't.
• Join one of the Mailing Lists and post your question there.

There is a difference between editing pages and editing scripts - CAUTION!

A script is a PHP program. It is in a file with a .php extension. You find them in the pmwiki directory, the pmwiki/scripts, the pmwiki/cookbook directory, and the pmwiki/local directory. You make changes to these using your favorite editor, perhaps using FTP to download/upload the file before/after you edit it.

The files you find in wiki.d and wikilib.d are NOT scripts! You do not edit these in the same way you edit a file! You should NEVER go into wiki.d/ and wikilib.d/ and try to edit a file there using an editor unless you really know what you are doing. Instead you navigate to that page using your web-browser and then click the Edit link or else append ?action=edit to the end of your URL. See (fill in link) for more details on editing pages.

Again, be very careful to differentiate between pages and scripts when you are making changes to your site. Treating one as the other or visa versa can completely mess up your system.

Change log / Release notes

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See also

Contributors

• Peter Bowers

Comments

See discussion at AdminHints-Talk