TWiki support is provided by users and developers in their spare time
- nobody is paid to do this. So it's important that you provide enough information in your support question to resolve your problem in an efficient way - hence these guidelines.
'How do I do this?' questions
Questions about whether TWiki can do something are fine and don't need all the installation specifics (i.e. perl version, which browser, etc.). However, please supply the TWiki version
you are using:
- TWiki 04-Sep-2004 and earlier - available from your installation's TWiki.WebHome topic; also reported by the
twiki/bin/testenv script (latest version at SVNget:bin/testenv)
- TWiki-4.0 and later - available from the
configure script and from
lib/TWiki.pm (please report values of
'Something is not working' questions
For all other questions, please read the rest of this page and supply full details.
Reporting your configuration easily using
TWiki developers try to make installation easy, self-explanatory and painless. The
script is an "Installation Expert" - a program with preprogrammed knowledge of what might go wrong during an average installation. You may be able to solve your problem with this tool alone.
TWiki releases before TWiki-4.0 (Feb 2006) used a script called
that is used just for diagnostics, not to configure the system.
To report the
output, be sure to click the expand all options
, then save the whole output of configure
, as an HTML file, and Attach this to the support request (under More topic actions
link at bottom of page.
This makes it much
easier to solve your problem since the HTML output is clearly formatted and includes all information. You can trim out sensitive information (such as URL and file paths) before attaching the file.
- Note: If for security reasons you do not want to attach the output of the
configure script to the public TWiki.org website, you could offer to send it upon request by e-mail.
Asking support questions about international characters ()
Here are some tips to help you get your I18N
(internationalisation) issues resolved when raising questions in the Support web:
- Provide a simplified example that shows exactly what the problem is - screenshots are a really good idea, with some text or graphics to highlight the error.
- Remember that the person helping you with your support question may not speak the language your site is using. They may not even be able to read the characters, in the case of Chinese, Japanese or most non-European languages - simplified examples with highlighted errors are very important for this reason.
- Upload the raw text of the topic (i.e. the topic's
.txt file) for your simplified example, as an attachment - it's important to do this, so that the characters are not translated into ISO-8859-1, the character encoding used by TWiki. (You can ignore this if you're using ISO-8859-1, but it's still useful to have this attachment).
The good news is that we have been able to debug most I18N
problems even for character sets that we are not able to read.
Tutorial on common CGI and Unix/Linux problems
This tutorial on CGI script setup
is very good for people who are new to Linux, Perl and CGI (the technique by which the web server runs the TWiki scripts).
Check for Known Issues
See the Support home page
for a link to the 'KnownIssues' page for the release you are using - significant problems may already be solved. Also check the TWikiFAQ
Don't add your question to an existing page!
Adding questions to an existing question page is not
the way to go - this tends to result in a rather confusing page, and the follow-on questions never
have enough information. Just create a new question page, starting at WebHome
(once you've read the existing questions, done a search, and so on) and create links to existing questions that seem similar (or from existing questions to your new one, perhaps).
The result is that we can see you did your homework and that your question really is
different from one that's already asked. This also means your question is less likely to be missed, as many people only look for new question topics.
Finally, questions added to an existing page are frequently missed since they are often under AnsweredQuestions
whereas people who are helping with Support look at AskedQuestions
Asking yourself the right questions
Any support request that just says "it's not working" is basically useless
- it doesn't help anyone understand exactly what is going on, which is an essential step to fixing your problem.
Some key questions to ask yourself are:
- What happens? Symptoms are good, but what are the exact error messages, in the browser and the server error logs?
configure output is very helpful - provide a URL if you have an Internet-hosted TWiki, otherwise attach the output of
- When does the problem happen? What were you doing? Does it happen on all scripts?
- Did you just change your TWiki setup, e.g. installing a new plugin or customising a script?
Please provide at least
the following information - additional detail is welcome where relevant.
You can get most of this info using
- TWiki version
- List of installed plugins ()
- Plugins can create problems of their own - try disabling as many plugins as possible if you have some non-standard plugins installed (i.e. those not installed as part of the TWiki distribution). The
$disableAllPlugins switch in
lib/TWiki.cfg disables all Plugins at once.
- Web Server version
- Server OS version
uname -a on Unix/Linux
- Perl version and variant
- The variant matters if not on Unix/Linux, e.g. ActivePerl vs. Cygwin Perl on Windows
perl -v to find out, e.g. ActivePerl 5.6.1, Cygwin Perl 5.6.1, Unix Perl 5.005_03, etc.
Optional if it is clearly a server issue, but include this if you are not sure:
- Client OS version
- Browser version
This is essential
- without this, only telepaths will be able to help answer your question!
- Browser error messages or symptoms
- Web server log messages - these are critical to resolving many installation problems, so check there first - see TWikiDebugging for more information.
- TWiki warning messages from the TWiki warning log. See
configure if you are unsure of the path to this file.
- Often, you can find a solution most easily by using Google to search for 'twiki' together with the words in these error messages! Many TWiki problems have been solved already and are accessible via Google.
- (Optional) Links to your TWiki site - if it's Internet hosted, this can make it easier to diagnose the problem. For intranet TWikis this will not be possible, but consider uploading the HTML from a test page on your site.
This may seem like a lot of information, but a few minutes spent now will probably save you (and those helping you) a lot of wasted time. Providing this information means your question is much
more likely to be answered, and avoids an exchange of followup questions that may take several days.
If you provide a few lines of vague text saying that 'it's not working', you are greatly reducing the chances of your question being answered - see this page on how to report bugs effectively
And of course, please read the AskedQuestions
page and search for similar problems! TWiki is searchable using Google - just search for 'TWiki' and some keywords (often, searching for the error message displayed is very helpful).
Finally, once your question is answered (or someone has answered it for you) please mark the question as answered
using the form at the bottom of the edit page. Otherwise TWiki developers end up wasting a lot of time revisiting questions that have already been answered.
Any comments on this? I have created this page because of some recent questions that are so lacking in information as to be impossible to answer...
It might also be worth pointing to AdminSkillsAssumptions
- 28 Jul 2002
I added section explaining why latest
is so important. Maybe we should rename it: installwizard | answerwizard | twizard | something else?
IMHO we should remove form to add support question from WebHome
and place it at the end of this page. So even less patient users will have to read guidelines above - no way to post questions before reading it all.
- 07 Dec 2002
Thanks for the updates, definitely very useful! I've gone through them to make a few clarifications. I hope we are not overselling
but it is fair to call it an installation expert.
I like your idea about putting the new-question request at the end of this page... Should also have link here to TWiki InstallationFAQs
- 16 Feb 2003
Refactored for TWiki-4.0
- 12 Mar 2006
I could do with a section with a short lifecycle for support requests, I will try to think of one. For now I just need a line like "If your request is without an answer for a month, it will be put in the ClosedUnanswered
set", but other stateshifts could be interesting as well.
- 03 Jul 2006
How about, support requests are closed automatically 30 days after the last edit.
- 03 Jul 2006
Sounds interesting, could you elaborate on the closed automatically part? Script / TWikiShell?
- personally i fail to see why a plugin would not be sufficient, but i didn't elaborate, cos i'd rather hear your creative thoughts. -- SD
- Ah, ok .. if this becomes unmanagable suddenly, I'll get back to a fallback mechanism .. for now it looks possible to keep the # of support requests in an ok low state, allowing for manual handling with a reasonable effort. -- SteffenPoulsen - 03 Jul 2006
- 03 Jul 2006
Update above about asking support questions on I18N
- 12 Nov 2006