create new tag
, view all tags

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 (NEW)

Here are some tips to help you get your I18N (internationalisation) issues resolved when raising questions in the Support web:

  1. 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.
  2. 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 (NEW)
    • 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.

  • IDEA! 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.

-- RichardDonkin - 28 Jul 2002

I added section explaining why latest testenv is so important. Maybe we should rename it: installwizard | answerwizard | twizard | something else? wink

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. wink

-- 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 smile .. 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

Edit | Attach | Watch | Print version | History: r42 < r41 < r40 < r39 < r38 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r42 - 2007-07-12 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.