Short Version

If you are feeling like you have a question that LPI should be asking, please read the item writing guide.

Although it is not a requirement, it would be nice if you would first contact LPI's exam development community here (lpi-examdev). There you can get in touch with LPI's staff and other authors who would help you, if you need assistance.

Then, head over to the LPI Item Contribution Tool and submit it (you do need an LPI ID to login).

Terminology

When talking about exam development, the following terms are likely to be used:

„Item“ is an exam question including all provided answers for SC/MC items.
„Single Choice“ or „SC“ is an item that provides four or five answers from which one is correct.
„Multiple Choice“ or „MC“ is an item that provides five answers from which one to three is/are correct.
„Fill In The Blank“ or „FITB“ is an item that is answers by a string and does not provide answers to choose from.
„Stem“ is the question part of an item.
„Distractor“ or „Foil“ is a wrong answer offered in addition to the correct answer(s) in SC/MC items.
„Computer Based Tests“ or „CBT“ are electronically delivered exams, as delivered at test centers.
„Paper Based Tests“ or „PBT“ are exams that are delivered using question booklets and answer sheets, both of paper and are usually delivered at community events and wherever else CBT aren't possible .

General rules for item writing

The following rules should be obeyed when writing items. Exceptions should be considered well as they probably indicate bad items.

Do not mix objectives. Test only one topic and one aspect per item.
Write independent items. Each item must be answerable for itself without referring to any other item.
Ask straight. The item should test the Linux skills of the candidate, not his competence in (foreign) languages and logical skills for unwrapping nested negations etc. .
Use easy language. Use a homogeneous wording and avoid complex sentences.
Be specific. All correct answers must absolutely and in all circumstances fit the question. None of the distractors may not even eventually be considered correct no matter how.
Be or not be. Each answers must be true or false without any consideration. Never ask for the “best” or “most likely” answer or use conditions like “could be” or “might be”.
Keep items simple. Do not provide unnecessary or anecdotal information.
Begin with a W-word. To make the question clear to the candidate it is best to begin a steam with a W word like 'What' or 'Which'.
Create enough distractors. For SC/MC items, try to provide at least three, better four distractors and see to it, that they seem possible. If it is hard to find good distractors, consider changing the item to FITB or to retire it.
Create plausible distractors. Instead of asking something completely irrational, obviously wrong or out of context, create distractors that sound plausible to someone trying to guess but must be unambiguous to an expert.
Create distractors of similar length. Distractors should not vary in length too much. That prevents helping candidates to distinguish correct answers and foils.
Ask for short and authentic answers for FITB items. Ask FIBT items only for text that would be entered exactly like that in a terminal. Never ask for verbal descriptions or other human language. Ask for example for single commands, programs, files or parameters but do not ask the candidate to complete a sentence by entering a noun.
Be comprehensive for FITB answers. When several answers are possible for a FITB item, provide all of them, each as an own correct answers.
Keep items short. Remember that the items should still fit into a 800x600 screen and that FITB answers must be written to the limited space of a PBT form.
Don't reveal too much. The steam of an item should not disclose the answers to other questions.
Be urbane. Avoid cultural specifics, regional terminology and slang.
Be neutral. Never use judging adjectives. Do not let persons like „The system administrator“ appear and do something that could better be expressed as a neutral description of the resulting situation.
Do not directly address the candidate. Never use personal pronouns like „you“ or „one“. Instead of describing human actions, describe technical situations and facts. The reason for this last rule is that items will be translated in other languages and for other cultures.

Item Style Guide

In order to give our items a homogeneous appearance we created the following boilerplates and best practices which should be used in all items. There is however no guarantee that all items are formed as described herein.

Number of right answers in multiple choice items

In case only one answer is correct do not mention it. This is the default case and having items that ask "which one is correct" is redundant.

In case more than one answer is correct, specify this by appending exact one of those brackets to the item:

(Choose TWO correct answers.)
(Choose THREE correct answers.)
(Choose FOUR correct answers.)

Do not mention the number of correct answers in the stem. For example, "Which THREE commands would..." shouldn't occur, but plural may be necessary...

Asking for commands and files in fill-in-the-blank items

Asking for commands

Do not ask for the full path to commands if possible. Candidates should specify the command name only. This is because locations may change and because full paths become long (which is hard in PBT) and offer more characters to get wrong.

Asking for single command names without parameters

When only commands are asked for, append the following to the question:

(Specify ONLY the command without any path or parameters.)

Asking for full command including parameters

If a full command is asked for, append the following to the question:

(Specify the command without any path but INCLUDING ALL REQUIRED PARAMETERS.)

Asking for file and directory names

When asking for a file or directory either ask for the name or the full path and specify it by those appendices to the question:

(Specify the file name only without any path.)
(Specify the full name of the file, including path.)
(Specify the full path to the directory.)

In all these cases do not include such information in the answers itself.

Asking for options and parameters

When asking just for an option name:

(Specify ONLY the option name without any values or parameters.)

When asking for a variable name:

(Specify ONLY the variable name without any values or operators.)

Asking for numbers

When asking for numbers the following appendix should be used:

(Specify the number using digits only.)

Using IP addresses and DNS names in Items

When talking about global IP addresses and DNS names we use only IP addresses and DNS Zones that are reserved for documentation purposes. We do not use IP addresses that are officially assigned to any party. Private addresses should only be used when we refer to their special semantics.

IPv4 addresses

Within the IPv4 address space the following subnets are reserved for documentation purposes:

192.0.2.0/24 (TEST-NET-1)
198.51.100.0/24 (TEST-NET-2)
203.0.113.0/24 (TEST-NET-3)

IPv6 addresses

For IPv6 the following prefix is reserved for documentation purposes:

2001:db8::/32

ULAs and LLAs should only be used when we explicitly talk about them. Site-local addresses are deprecated and should not be used.

DNS names

For DNS names the following zones are reserves for examples and documentation:

example.
example.com.
example.net.
example.org.

When using DNS names in items, names from these domains should be used. The only exception is when the content of an item requires asking a real domain. This should however avoided as real names may change. It is i.e. not a good idea to ask for project websites etc. .

Using Named Entitied (like Files, Directories, Paths, Users, Groups, Hosts, ...) in Items

To avoid confusion of candidates the item should be worded as simple as possible. The following rules may help to create items that focus on the real topic of the question:

Use English terms only. Never use words in foreign languages, not even for names of files, directories, hosts etc., as this may confuse and sidetrack candidates. Use English terms only and do not translate them in any way. For example use the file calendar.ics or the host node-1 instead of localized names like calendario-della-settimana.ics or Rechenknoten-1.

Files, Directories and Paths

Directory names always end in a /.
Do not abuse system files for items that are not related to this file. For example, an item testing chmod should use a file like file-a.txt instead of /var/log/syslog (unless, of course, specific aspects of /var/log/syslog are tested.
When asking for a specific path or name of a file, point out whether the answer is the name of the file, path to the file or the fully qualified name of the file (including path and file name).
Remember to put names of files and directories in <tt>-tags. That will show them in fixed font and prevent them from being translated.
When in doubt, use the file filea.txt, fileb.txt, ..., located in the home directory of the current user (~) or somewhere below that (e.g. in ~/dira/).

Users and Groups

Do not abuse system users or groups that serve a special purpose unless explicitly that purpose is tested.
Avoid terms that refer to other aspects of a Linux system unless it is explicitly intended. For example, do not use a user fsck just to demonstrate useradd.
Keep user and group names consistent in all answers of an item.
Remember to put names of users and groups in <tt>-tags. That will show them in fixed font and prevent them from being translated.
When in doubt, use usernames like usera, userb, ... and similar group names.

Hostnames

Try to use senseful hostnames like webserver or workstation when it fits to the context of the question.
Avoid hostnames that have an unintended meaning like broken-server.
When in doubt, use hostnames like hosta, hostb, ... .

Grammar, syntax and expressions

Answers

If possible, answers should either be commands, nouns or full sentences. Accordingly, they are formatted and phrased as follows:

If an answer is a command, it is literally written as is would be entered into a shell and must be enclosed by <tt> tags without any additional punctuation marks.
If an answer is a full sentence, it must have an initial capital letter and a final period. If an answers consist of several sentences, each of them is formed like this.
If an answer is an abbreviation or acronym, it should be written in it's original notation with respect to capital / lower letters and without any additional punctuation mark.
If an answer finishes a sentence that was begun in the stem, it should have a final period. This kind of items is considered very bad style and is strongly discouraged!

Item formatting and markup

In general, items are written without any explicit formatting. There are however three exceptions:

The fixed font (or console font or monospaced font) must be used for terms that, when used in the context of the item, would be literally displayed on the system console.
Bold font is used to point the candidate to important meta-information regarding the item.
In rare circumstances line
breaks may be added to the stem.

Note: italics are never used in items!

Bold font formatting

When to use bold formatting

With two exceptions bold font is never used in the main stem or the answers of an item. The two exceptions are: when asking for something that is NOT correct and within the boilerplates described above to point the candidate to the number or correct answers or the kind of information expected in a FITB item.

How to use bold formatting

Bold formatting is done by enclosing the bold term with the tags and .

Fixed font formatting / „TT'ing“

ATTENTION: It is important to know that translators will not translate any text with fixed font format. It is therefore important to obey the following rules, to ensure that the item is working in every language!

Everything that appears on a terminal is printed in fixed font when it is used in exactly the same way and context that would make it appear on a terminal. Everything else mustn't use fixed font.

Note: Prompts are never shown in LPI exams. Avoid full console captures including a prompt, a command and the output of that command as this makes it hard for the candidate to determine what is input and what is output. Instead, create a question like 'In case the command foo leads to the following output: ...'.

What to put in TTs

In the following circumstances TT-tags must be used:

Command names when they are used as a command. For example <tt>apache2</tt> is TT'ed when talking about the command. Apache HTTPD is not TT'ed when talking about the webserver product. If a command is shown with options, parameters or file names, the full command is TT'ed.
Output of commands like <tt>ls: cannot access Directory: No such file or directory</tt>.
Names of processes and daemons when talking about specific aspect. For example, the process <tt>exim4</tt> is TT'ed whereas the mailserver Exim 4 is not.
File names and paths like <tt>/etc/passwd</tt> or <tt>/usr/share/doc/</tt>.
Variable names like <tt>PATH</tt> or <tt>$DISPLAY</tt>.
Regular expressions and globs like <tt>ab?.txt</tt>.
User and group names like <tt>root</tt> and <tt>staff</tt>.
Network interfaces like <tt>eth0</tt>, <tt>eth1</tt>, <tt>ppp0</tt>.
Signal names like <tt>SIGHUP</tt> or <tt>SIGINT</tt>.
Content of text files like <tt>root:x:0:0:root:/root:/bin/bash</tt>

What NOT to put in TTs

In the following circumstances TT-tags must NOT be used:

Program, project or technology names. For example, the Apache HTTPD is not TT'ed as it is the name of a product and not of a distinct command.
Abbreviations and acronyms like PCI, ACPI, LAMP are never formated in any special way.

How to use fixed font formating

Fixed font formatting can be done either inline using ttv>TT-Tags</tt> or for whole paragraphs using

<pre>
Tags
</pre>

tt-tags just put the string enclosed by them in fixed font. This is the usual way commands, files etc. are marked up in both the stem and the answers. If an answer contains just a command name, the full answer is enclosed in tt-tags.

A pre-environment is used when the stem or the answers contain several following lines, like for example the output of a command or the content of a file. Within the pre-environment text is used literally, i.e. line-breaks within the pre-environment are shown as line breaks in the exam. Therefore the content of a pre-environment can be just put into it without any additional modification like e.g. without adding tags.

Note: When rendering an exam, <pre> and </pre> tags become a new, empty line. This should be avoided which is why the tags should be put on the first and the last line of the presented text and not on distinct lines. The following example illustrates this:

<pre>root:x:0:0:root:/root:/bin/bash
bin:x:1:1:bin:/bin:/bin/false
daemon:x:2:2:daemon:/sbin:/bin/false</pre>

Line breaks

Line breaks may be used to give large stems some structure. As items should be as short as possible this should no often be the case! If -- after some intense rethinking the item -- it is necessary, tags are used for this purpose.

Hints for translators

Text that is formatted in fixed font may never be translated in any way. Though terms like at or date seem English, they always are “system language” are are universally valid. Editing those terms may easily change the sense of an item or break implications of the original wording. Translating text in fixed font may easily affect the correctness of the item!

This does however not mean that everything else may be arbitrary translated! Translators must have appropriate technological knowledge in order to fully understand the item and to determine what to translate and what to keep. Also, translators must be familiar with the professional language and the technical terms used in the destination language. LPI exams should never be translated by non-technicians only.

@@ Line 31: / Line 31: @@
 * '''Create enough distractors.''' For SC/MC items, try to provide at least three, better four distractors and see to it, that they seem possible. If it is hard to find good distractors, consider changing the item to FITB or to retire it.
 * '''Create plausible distractors.''' Instead of asking something completely irrational, obviously wrong or out of context, create distractors that sound plausible to someone trying to guess but must be unambiguous to an expert.
-* '''Create distractors of similar length.''' Distractors should vary in length too much. That prevents helping candidates to distinguish correct answers and foils.
+* '''Create distractors of similar length.''' Distractors should not vary in length too much. That prevents helping candidates to distinguish correct answers and foils.
 * '''Ask for short and authentic answers for FITB items.''' Ask FIBT items only for text that would be entered exactly like that in a terminal. Never ask for verbal descriptions or other human language. Ask for example for single commands, programs, files or parameters but do not ask the candidate to complete a sentence by entering a noun.
 * '''Be comprehensive for FITB answers.''' When several answers are possible for a FITB item, provide all of them, each as an own correct answers.

VolunteerItemWriting: Difference between revisions

Revision as of 13:05, 22 August 2014