AdminHints

Summary: Hints & suggestions for wiki administrators
Status: Documentation
Maintainer: Varied
Categories: Administration
Users: (view? / edit)
Discussion: AdminHints-Talk

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.

NOTE: If this stuff is already covered somewhere else, please let me know and I'll move over there... —Peter Bowers

Keep your software up to date

Keep the PmWiki software up to date for many reasons

Keep cookbook recipes up to date. Use one of the following to check your software versions

Backup regularly, keeping a history

Backup configuration

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

  • local/
  • pub/

and to make it easy to recover also include

  • cookbook/

Backup data

Wiki data is contained in the following directories

  • wiki.d/
  • uploads/

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

Simple file-copy 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.YYYY-MM-DD.php. 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.

Note that changing the ".php" extension of a config file to something else may cause the file source to become readable by a visitor, without the file being processed by PHP. You should estimate if this is a security risk. Notably, it would be a risk if passwords are kept in clear like crypt('MyPassword7') instead of '$1$rTaE6G6x$dbM4NpjJruIQD6afpqbfc0'

Version Control

"Proper" backup consists of version control - such as Subversion, Git, or CVS. Depending on your wants and needs, uploads (generally, non-text binary files) could or should be excluded from version control, and only be part of backups.

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.

Document Changes

The best place to document changes is on you wiki itself. Alternatives are a physical notebook in which to write things down, or 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.

Make use of the [(approve links) edit diff] by keeping your notes in the wiki. If your wiki is public, you probably do not want to make these notes public; set the attributes to keep the notes (or possibly the entire group) private for your login. SiteAdmin is one good location for these notes.

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. Date of change and reason for change are good starters; if inserting a recipe you might want to note the source URL (likely from the cookbook).

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

  • see How To Get Assistance
  • 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

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.

  • it is highly recommended that you never edit pmwiki.php or any file in the scripts/ folder, these are system files and would be overwritten when updating PmWiki software.

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 creating new pages and basic editing 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.

See also

Contributors

Comments

See discussion at AdminHints-Talk