======  Documentation in Research Papers ======

As a rule, the survey is only one part of a study where the results have to prepared in written form. The questionnaire is added to the appendix as a surveying method. This section provides tips how to achieve an aesthetically pleasing result (in Windows). The methods described can be used on other operating systems, but other software is needed for some parts.

There are various ways to prepare the questionnaire for documentation in a thesis. The basic procedure is always the same:

  - The questionnaire is called up page by page and
  - each page is converted into a PDF file or an image.
  - This image can then be included in the documentation.
 
**Note:** Converting the complete questionnaire in one single step is not possible. Nor does SoSci Survey support the direct export of the complete questionnaire as a PDF. In **Compose Questionnaire**, there is a //Galley-proof// which can be used to display a proof or a general view of the complete questionnaire.   


===== The Challenge =====

**Note:** Documentation is actually only challenging if the questionnaire is meant to look good in print as well. Simply taking a screenshot is enough for documentation in a PowerPoint presentation. 

A typical printer's resolution is significantly higher than that of a computer screen's. This means finer structures are a lot more visible. If the screen was simply printed 1:1, the result would look blocky and/or blurry. Take a close look at this **A** and compare it with a printed "A" in a newspaper or a letter. The following image shows the letters in 10x magnification.

{{:de:results:div.documentation.screen10.png?nolink|Letter A in Screen and Print Resolution}}

A questionnaire that looks good on screen looks just as unappealing as this does when printed as a screenshot (see image below).

However, if you print the questionnaire page directly in the browser (//File// -> //Print//), it keeps the edges and letters razor-sharp. This is because the browser sends the original text to the printer, rather than the screen content. The printer creates (screens) an image from this with a higher resolution that it subsequently prints. The low screen resolution is only seen if the internet page contains images -- these lack the fine structures needed to ensure an adequate print out. 

{{:de:results:div.documentation.screen.png?nolink|Insufficient Fine Structures on the Screen}}

Of course, you could print out each page in the questionnaire and then scan them in. A more compact way of doing this is to virtually print the internet page as a PDF file (the original text will also be saved here), and then convert this PDF file into a graphic.


As mentioned earlier: the additional effort is only worth it if the questionnaire will be published in a document that should look good in print. A screenshot is enough to show the screen display.
 

===== Various Options =====

The following overview shows a few different options that can be used to create the documentation:

^Option^Advantages^Disadvantages^Recommendation^
|[[#print_questionnaire|Print Questionnaire Directly in the Browswer]]|Simplest solution|Cannot be used in another document, no page numbers etc.|When under deadline pressure, to proofread|
|[[#screenshot_with_windows|Screenshot with Windows]]|No additional software|Poor print quality, rework needed with graphics program, additional effort when there is scrolling text on a questionnaire page|Do not use|
|[[#screenshot_with_program|Screenshot with Firefox Plugin]]|Very convenient|Poor print quality, installation of plugin, limited to Firefox|To view on-screen|
|[[#create_and_convert_PDF|Create and Convert PDF]]|Optimal quality|Installation of software, rework needed with graphics program|For top quality printing results|

===== Print Questionnaire =====

Printing a questionnaire page in the browser is very simple: //File// -> //Print//. 

Depending on the intended purpose, the following settings (for example in Firefox //File// -> //Page Setup//) could be useful:

  *  Select option //Print Background// to ensure colored areas in the layout and item shadings are printed correctly. 
  * Enable option //Shrink To Fit Page Width// in //Scaling//. This means each questionnaire page will be adjusted to fit the print page.
  * Disable or adjust headers and footers if the printouts are being used in directly in a publication. 

===== Screenshot with Windows =====

Most operating systems let you take a screenshot very easily. In Windows, push the //Print Screen// key (can also sometimes be //PrtScr//, //Prnt Scrn//, or //Print Scr//) to take the screenshot. This copies the current screen as an image into the clipboard.


   * After this, open any graphic program ([[http://www.gimp.org/|GIMP]] is a free alternative that comes highly recommended)
   * and create a new image from the content of the clipboard (in GIMP 2: //File// -> //Acquire// -> //From Clipboard//).
   * Crop the margins because the browser will be photographed alongside it. In GIMP you can crop images as follows:
     * Use the Rectangle Select icon to select part of the questionnaire and then
     * **Image** -> **Crop Image**
   * The result will be saved as a PNG image. Avoid using a JPEG format for screenshots as this can lead to a loss in quality depending on the settings.  

If the page of the questionnaire is too long, stick multiple screenshots together:

   * First of all, make room for the image: make the image "higher" in **Image** -> **Canvas Size**, and break the "chain" before inputting the height
   * Insert the next screenshot as a new layer
     * //Print// key
     * Then in GIMP //Edit// -> //Paste//
     * right-click -> //Layer// -> //New Layer//. 
   * The Move Tool can be used to move this snippet (i.e. the layer) into the right position
   * and using the Rectangle Selection icon and //Edit// - //Cut// (Strg+X) allows any unnecessary image components (part of browser seen in the screenshot) to be removed.
   
===== Screenshot with a Program =====

There are a range of programs that automatically scroll down to capture a screenshot. If you have Firefox ready to hand, the [[https://addons.mozilla.org/de/firefox/addon/fireshot/|FireShot]] plugin or [[https://addons.mozilla.org/de/firefox/addon/screenshot-pimp-screengrab-scr/|Screenshot Pimp]] are provided in order to do this. 

Both plugins are able to save the entire website as a PNG image file. This means you do not have to put bits of pages together -- and you do not have to remove the browser from the image. 

=====  Create and Convert PDF =====

The questionnaire page is initially "printed" using this solution. Letters are saved as real letters here, instead of small groups of pixels.


  * If you already have the option to print to a PDF then you can skip the following excursus.
  * The same results can be obtained by using Adobe Acrobat or a different software that creates PDFs.
  * There are also FireFox plugins that save a webpage directly as a PDF -- however, these work with varying degrees of quality.
  
====  Install PDF Printer (Windows) ====

Below is a brief description of how to install a PDF printer on your (Windows) system using free software. Two programs are needed:

  - GhostScript -- a program that generates PDF files out of PostScipt
  - FreePDF -- a program that creates a PDF printer for GhostScript

Both programs can be downloaded on the [[http://www.freepdfxp.de|FreePDF-Homepage]]. Install GhostScript first of all, and then FreePDF. You may have to restart your computer afterwards. If everything went according to plan, you will have a printer called "FreePDF". Everything that you "print" from this printer will be saved as a PDF file.
====  Install PDF Printer (Mac OS) ====

Mac OS X (and newer) already has a PDF printer: in the printing dialogue (at the top where you select a printer), there is a "PDF" button at the bottom left.

Alternatively, there are also a few [[http://www.heise.de/download/apple/office/pdf/erzeuger-konverter-50002505012/|programs for Max OS, that act as a PDF printer]], for example [[http://www.cups-pdf.de/|CUPS PDF]].

==== Convert a Questionnaire Page into a PDF ====

As every page in the questionnaire represents an individual HTML page, there is a considerable amount of work to do: you have to "print" each page as a PDF. Once you have selected the PDF printer (in the example "FreePDF"), select a profile, compress the image a little ("High Quality"), and save the outcome as a PDF file (//File//, specify file name, //Save//).


**Caution**: Internet Explorer is totally unsuitable for "printing"! This is because it wants to save ink and therefore drops background images and colors. This means the questionnaire will not be rendered in the same way it really looks.

**Note:** In some browser versions, the print preview may look completely different to what is on the screen. To ensure the selection fields are the same size as on the screen, sometimes you have have to adjust the zoom level __before printing__.

Firefox and Opera are browsers that have proven to be effective. In Firefox, set background images to be printed in //File// -> //Page Setup//. In addition to this, you can also set the scale. Selecting the //Shrink To Fit Page Width// option is generally okay to do -- however, particularly long questionnaire pages will be spread out across several pages. If this is the case, it helps to use a smaller scale (e.g. 80% or 50%).

Check the result with Acrobat Reader by opening the PDF file. If everything went according to plan, you will now have one PDF file for each page in the questionnaire.

===  Alternative: Web Services ===

Some internet services convert websites into a PDF. This saves installing a (generally useful) PDF converter. For example, [http://www.web2pdfconvert.com/|Baltsoft Web2PDF]], [[http://pdfmyurl.com/|Opentracker PDFmyURL]] oder (mit viel Werbung) [[http://www.htm2pdf.co.uk/|HTM2PDF]] offer this.

**Note:** If the questionnaire juts over a standard sized page, the page cannot just be scaled to a smaller size as can be done with the browser and PDF printer

To make sure the converter uses the correct page in the questionnaire, you have to open the questionnaire in the browser yourself, and convert the address in the browser address bar after each time //Next// is clicked on. Sometimes, JavaScript supported questions such as a 'Selection Sequence' are unable to fully converted when using this option.

===  Alternative: Special Software ===

The free basic version of [[http://www.7-pdf.de/en/products/7-pdf-website-converter|7-PDF Website Converter]] converts websites into PDFs that remain true to the original. The page size can freely defined here to make sure larger questionnaire pages fit onto a PDF page.

The same goes for here too: to make sure the converter uses the correct page in the questionnaire, you have to open the browser at the same time and convert the address in the browser address bar after "Next" is clicked on each time. JavaScript supported questions such as a 'Selection Sequence' may also be unable to be fully converted when using this option.


====  Convert PDF into an Image ====

It now makes sense to convert the PDF into a raster graphic -- it is easier to retouch (where necessary), and also simpler to insert into a document.

A 600 dpi resolution is a good rule of thumb. The width and height have to be specified in pixels, so a width of 5000 pixels is a suitable value for a A4 page (210 mm = 8,3 Zoll × 600 dpi = approx. 5000 pixels).

**Option 1:** If you have a graphics program that can open PDF files, then this is a good solution. One slight note of caution: although GIMP can open PDF files when used with GhostScript, you have set the environment variables manually in Windows -- not an easy task.  

**Option 2:** If you have the full version of Adobe Acrobat, you can save the opened PDF directly as a graphic (e.g. in PNG format) by going on //Save As//.

**Option 3:** Use the [[http://www.cs.wisc.edu/~ghost/gsview/|GSview]] program that you can get for free. Open the PDF file with this program and select //File// -> //Convert// in the menu, "png16m" (the "m" is important) as //Device//, //Resolution// "600" and //OK//. Then you have to specify where the file should be saved -- state a file name ending with ".png" (e.g. "page 1.png")!

Now you will have one (or if the questionnaire pages are longer) or several graphic files that display the questionnaire in a proper resolution. Once the PDF has been converted, the example above looks as follows:


{{:de:results:div.documentation.result.png?nolink|Result of Printing as PDF and Converting nto a Pixel Grafik}}

Reward for the PDF work: a high-resolution result (600 dpi, above left). Small (bottom right): the same snippet as in a screenshot.

Cut the resulting image in image editor (e.g. [http://www.gimp.org/|GIMP]) so only the questionnaire is shown. By exporting in portrait format you rarely have to combine several parts. More often than not you will spread a long questionnaire page across several print pages in the appendix.



=====  Display Errors and Optimization =====

Unfortunately, a few minor errors will always rise from time to time during conversion. For example, sometimes a small point appears in selection input fields (see figure). White stripes may also appear in some complicated layouts.  

Alas, these types of errors can only be remedied manually in the graphics program itself. No other program that creates PDF files or graphics exists at this moment in time. However, in general, changes needed to be made are kept within a certain limit.
 


====  Problems with Transparency ====

One problem that unfortunately always comes up with this approach is dealing with transparency. If, for example, Opera 8 is used as a browser instead of Firefox, white rectangles appear around the selection fields. The problem worsens with transparent graphics (e.g. the SoSci Survey logo), which gets given a white background after conversion.

Sometimes graphic scale anchors ("wedges") are also surrounded by an unattractive white frame.

This problem also has to be solved in the retouching stage. The simplest way of doing so is to take the background color using a pipette, and fill in the affected areas.


====  Problems with Graphics ====

If graphics (e.g. logos) appear in the questionnaire, then initially only a poor resolution version of the graphic is available with the file. Most of the time you have to just leave it like so.

Sometimes, however, a higher-quality resolution version is available (e.g. the original file of the logo before the resolution was reduced for use on the internet). If this is the case, the higher resolution file can be inserted into the display of the questionnaire and scaled accordingly.

The same goes for graphic anchorage in scales. If it should be shown in better quality, the wedge has to be available in high-resolution. A wedge's image address can be invoked in SoSci Survey just by specifying higher width and height.

What the amendments involve exactly - whether it be further optimization, or if the problem is due to the original questionnaire being corrupted - has to be clarified on the basis of each individual case.


==== Special Case: Dropdown Selection ====

A dropdown selection always appears incomplete in both the screenshot and the PDF version -- i.e. without its options. It would be make sense to show the different options in the display of the questionnaire as well. Open the questionnaire in the browser to do so, open the dropdown selection by clicking on it, and create a screenshot. 

When working in the graphic editing software afterwards, cut the selection options and paste them in a suitable place in the documentation (e.g. next to the questionnaire display). Needless to say, the screenshot has a restricted resolution only -- if you want to do a perfect job, the website that takes the screenshot can be made larger in Opera or Firefox by using the zoom function. 

==== Filters and Dynamic Content ====

If there are various routes that can be taken in the questionnaire, then this can be difficult to portray in a static image. One possible solution is to change the optional pages or questions into images using the approach described above, and then to include this in the documentation with an explanation, e.g. "The following question will only be shown if the respondent answered "yes" to question no.7".

Sometimes, the finished image of the questionnaire can be divided into several parts. If dynamic content crops up in the questionnaire (e.g. brand names shown with a random generator), these have to be specified in the text just like a randomized item order.
