====== Improving the Manual ======

Is the manual unclear or incomplete? Is important content missing? Are some pages not available in all languages?

Then help us: Make the manual better!


===== How Can I Change Something? =====

You need a user account on SoSciSurvey.de [[http://www.soscisurvey.de]] to edit the manual. If you are logged in on www.soscisurvey.de, you are automatically logged in to the manual as well. With the book symbol at the top left in SoSci Survey, you can also go directly to the manual.

As soon as you are logged in, you will see a button //Edit this page// at the bottom left of the manual; only a few individual pages cannot be edited. On pages with several headings, you will also see a small button //Edit// at the bottom right of each section, to edit the individual section.

Then the text can easily be changed. For formatting the text, shortcuts similar to those of Wikipedia are used. You will always find further explanations on formatting text under [[:en:wiki:syntax|syntax]] (also available in the edit mode).

**Note:** If you do not see any buttons for editing or logging in, you are probably in an offline copy of the manual. In this case, click through to the [[https://www.soscisurvey.de/help/|current manual]] on SoSciSurvey.de.


===== What Do I Have to Consider? =====

  * Please make sure that your changes improve the manual, e.g., make it more up to date, more complete, or easier to understand.
  * Don't worry: Should something go wrong, the administrator can undo the changes.
  * Before saving your changes, please always use the preview function and check whether everything looks as expected.
  * If you are not sure about something, simply ask in the [[https://support.soscisurvey.de/|online support]].
  * If you miss some content, please note it further down on this page.


===== Emphasis in Texts =====

To make it easy to find your way around the manual, the following formatting conventions are helpful.

  * The title of the chapter is a first-level heading\ e.g. ''%%====== Title of the Chapter ======%%''
  * The headings within the chapter are second-level headings, subdivisions are third-level headings\ e.g. ''%%===== Heading within the Chapter =====%%''\ e.g. ''%%==== Subdivision within a Section ====%%''
  * Menu items of the program (in the navigation on the left) are set in bold\ e.g. ''%%Choose the menu item **Compose Questionnaire**%%''\ e.g. Choose the menu item **Compose Questionnaire**
  * Labels of tabs, buttons, and attributes are set in italics\ e.g. ''%%Click on //Create new questionnaire//%%''\ e.g. Click on //Create new questionnaire//
  * Text content is set in quotation marks\ e.g. ''%%Enter "default" as //ID//%%''\ e.g. Enter "default" as //ID//
  * Programming code is formatted as code in the text\ e.g. ''%%the command ''value()'' returns the respondent's answer%%''\ e.g. the command ''value()'' returns the respondent's answer
  * Notes, warnings, and tips are highlighted in bold\ e.g. ''%%**Tip:** You can include any HTML code in the questionnaire.%%''\ e.g. **Tip:** You can include any %%HTML code%% in the questionnaire.
  * Negations and other important words can be underlined -- but sparingly\ e.g. ''%%do __not__ underline everything that seems important at first%%''\ e.g. do __not__ underline everything that seems important at first

**Note:** After the old manual was converted to the wiki, many chapters have not yet been formatted accordingly -- this is not intentional, and you are very welcome to correct it.


===== Images in the Manual =====

Images make the manual vivid. If you take the trouble to create good figures and screenshots, the following guidelines ensure a uniform appearance.

**Note:** The manual almost exclusively uses graphics (usually with few colors) and hardly any photos. The following notes therefore do not refer to photos.

**Note:** If you want to replace an existing image, enter the same file name for //Upload as// that the old image had. In addition, check the box //Overwrite existing file//. Then the page with the image does not have to be adjusted any further. Of course, this only works if the new file uses the same file format (e.g., PNG or GIF).

  * Images shall not exceed a width of 600 pixels (incl. frame).
  * Screenshots and many other figures look best if they are surrounded by a white margin of approx. 10 pixels and around it a light gray frame (1 pixel, color #CCCCCC).
  * Reduce the number of colors to 2, 4, 8, 16, 32, 64, 128, or 256 colors before saving. The fewer colors you need, the faster the images load. Of course, the loading time is secondary -- above all, the image should look clean.
  * Save the graphic in the file format PNG.
  * Name the file according to the pattern: //type//.//page//.//content//.png
    * //type// describes the type: "scr" for a screenshot, "exp" for another exemplary image, "fig" for a schematic figure, "div" for other images
    * //page// describes the ID of the manual page. This page, for example, has the ID "contribute" (see the very top)
    * //content// briefly describes the content of the graphic, preferably in English, e.g., "item.delete", "question.place", or "convert-to-php"
  * To upload an image to the manual, use the picture frame symbol at the top among the symbols when editing the corresponding page (fourth symbol from the right).
  * Add a short description to the graphic when including it in the manual.\ e.g. ''%%{{scr.create.question.new.png?nolink|Create a new question in the list of questions}}%%''
  * Always choose the original size for display (no size specification when including it), if there are no compelling reasons for a reduced display.
  * You do not need to type the file name manually ([[:wiki:syntax#bilder_und_andere_dateien|Including images]]); after uploading an image in the wiki, a button appears to the left of the image to insert the image directly into the content. If you have clicked the symbol, choose //no link//, //left-aligned//, and //original size// as settings for the insertion.


===== Translating a Chapter =====
Thanks to a number of volunteers, SoSci Survey has been multilingual (German/English) since 2011. It can be switched by a language selector in you user account.
Since the beginning of 2015, the manual is also almost completely available in English -- only the latest chapters are still missing. Are you interested in translating one chapter?  Technically the translation of a text is quite simple:
  - First open the page you like to edit.
  - Make sure, that the English part of this chapter doesn’t exist yet.  You may notice, that the English flag at the left menu is still grey. If there is already an existing version, you’re welcomed to edit, enhance or actualize the current text.
  - Click on edit of the German version. 
  - Highlight the entire text by using (CTRL+A) and copy the text into the clip-board.
  - Select cancel.
  - Change to the English version at left. If there is no existing topic a message is displayed: „This topic does not exists yet“.
  - Click on „Create this page“.
  - Insert the German text from your clip-board (CTRL+V) into the empty space.
  - Now start translating the text. It’s a good idea to check your work by using the preview function – and don’t forget save your text from here to then.
    * Please switch the language in your user account to English to look up the correct labels in the user interface.
    * For headings, all relevant words (not and, or, not, is, ...) also start with a capital letter in the English translation.
    * For links to other pages please replace the '':de:...'' at the beginning with '':en:...''.
    * For images, feel free to take updated screenshots from the English GUI -- or alternatively leave the '':de:...''.
    * To make the translation go quickly, [[https://www.deepl.com/translator|DeepL]] is recommended for the rough stuff -- then there's more time for the finer details.
  - Thank you very much for your assistance!