Support Guidelines
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 $RELEASE
and $VERSION
)
'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 configure
TWiki developers try to make installation easy, self-explanatory and painless. The
configure
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.
Note: TWiki releases before TWiki-4.0 (Feb 2006) used a script called
testenv
that is used just for diagnostics, not to configure the system.
To report the
configure
output, be sure to click the
expand all options button in
configure
, 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 configure
.
- 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?
What's needed
Please provide
at least the following information - additional detail is welcome where relevant.
Server info
You can get most of this info using
configure
:
- TWiki version
- see
TWikiDocumentation.html
- 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
- try
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
- type
perl -v
to find out, e.g. ActivePerl 5.6.1, Cygwin Perl 5.6.1, Unix Perl 5.005_03, etc.
Client info
Optional if it is clearly a server issue, but include this if you are not sure:
- Client OS version
- Browser version
Error info
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.
Comments
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.
--
RichardDonkin - 28 Jul 2002
I added section explaining why
latest testenv
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.
--
PeterMasiar - 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
testenv
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 page.
--
RichardDonkin - 16 Feb 2003
Refactored for TWiki-4.0
--
CrawfordCurrie - 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.
--
SteffenPoulsen - 03 Jul 2006
How about, support requests are closed automatically 30 days after the last edit.
--
SvenDowideit - 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
--
SteffenPoulsen - 03 Jul 2006
Update above about asking support questions on
I18N.
--
RichardDonkin - 12 Nov 2006