Summary: Hints & suggestions for wiki administrators
Questions answered by this recipe
- What hints or suggestions can you give me as I begin administrating a new wiki?
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 the PmWiki software up to date for many reasons
- bug fixes
- updates for newer versions of PHP (your web host may no longer support older versions of PHP)
- improved functionality
Keep cookbook recipes up to date. Use one of the following to check your software versions
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.
This should include the following directories
and to make it easy to recover also include
Wiki data is contained in the following directories
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
Normally this consists of copying
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
"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.
- Start with a known, working state (test it to make sure it works!)
- Choose a single feature to install or enable
- Read the instructions carefully and follow the instructions exactly
- Test your single change. If it doesn't work go back to step #3 and re-read and check carefully
- 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.
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 WikiNature 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/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
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 discussion at AdminHints-Talk