bitmark Bit

Introduction

bitmark Bit is used to describe shareable, self-contained, interactive quiz or static content bits.

It can be used independently from bitmark Text and bitmark Book.

This means for your app, you don't have to support bitmark Text as long as you are not using styled information in your quizzes.

Furthermore, Bits can exist without a book. Bits are fully self-contained.

The documentation of the common bitmark tags and properties is described in the following chapters. Let's start with the common properties.

Bit Declaration [. ... : ... & ... : ...]

The declaration of a Bit defines the type and text format of the Bit and the type and format of the optional resource of a Bit.

The most simple Bit declaration defines only the Bit type. The text format defaults to plain text.

[.cloze]

{
    ...
    "bit": {
        "type": "cloze",
        "format": "text",
        ...
    }
    ...
}

Read like this: "This is a cloze quiz in plain text (with no additional resources)."

[.cloze:bitmark--&image]

{
    ...
    "bit": {
        "type": "cloze",
        "format": "bitmark--",
        "resource": {
            "type": "image",
            ...
        }
    },
    ...
}

Read like this: "This is a cloze quiz in bitmark-- with an image."

As you see, Bits can contain additional resources like images, audio and video as well as bitmark articles, documents (files), external documents and even deep links to web and native apps.

Resources themselves have a format:

{
    ...
    "bit": {
        "type": "cloze",
        "format": "bitmark--",
        "resource": {
            "type": "article",
            ...
            "article": {
                "format": "bitmark++",
                "body": ...
            },
            ...
        }
    },
    ...
}

Please find the detailed documentation about resources here.

If the format is not explicitly declared, the default text format of a Bit is chosen, which is plain text. Other supported formats are bitmark--, bitmark++.

Note

For internal use, you are free to use any text format. Markdown, but also html might be good choice in certain cases. However, html is probably not the best choice to target native mobile apps or to share your data with partners. Please let us know, if you think we should add official support for a certain text format.

bitmark	Description, Example
`[. ...]`	Type of the Bit
`[. ... : ...]`	Type and Text Format of the Bit
	Bit of type "cloze" `[.cloze]` This is a short form for `[.cloze:text]` as the default text format is "text" (plain text).
`[. ... & ...]`	Bit with a Resource
	Bit of type interview with a resource of type image `[.interview&image]` or better: "Interview quiz with Image"
`[. ... : ... & ... : ...]`	Type of Bit in a Specific Text Format with a Resource in a Specific Format
	If the text format is "bitmark--" or "bitmark++", properties, that are shown to the end user (for example the hint), allow bitmark--, but not bitmark++. bitmark++ is only allowed in the body of a Bit.
	Cloze quiz in bitmark-- `[.cloze:bitmark--] This is a [_cloze][?Other word for gap text].`
	`[.cloze:bitmark--&image:jpg] [&image:https://cdn.bitmark.cloud/cat.jpg] There is a fat [_cat][!animal] on the picture.`

Type tag must start at the beginning of a new line.

Please find all resource types and the reason why a Bit can only contain one resource and why this is no limitation, but a huge simplification, here.

Item, Lead [%...]

The item is the "number" of the quiz displayed to the user.

Iteam can also be chained to other tags. For example to the gap tag of a cloze to "number" the gap.

    ...
    "bit": {
        "type": "cloze",
        "format": "text",
        "item": [ { "type": "text", "text": "A10" } ],
        "lead": [],
        ...
    }
    ...

Item

bitmark	Description, Example
`[%...]`	Item
	Very short (max. a few characters), human readable identifier to reference the Bit in a human conversation.
	`[%A10]`
`[%...][%...]`	Item and Lead
	You can chain two items. The second item is called lead and contains a short text. Often used to soft group several bits by a subject.

Example with item and lead

[%A10][%In the Office]

Item

Instruction [!...]

Instructions are always shown to the user. Instructions are related to the whole quiz or to a chained tag. They are an integral element of the quiz.

The information in the instruction is needed to solve and understand the content or exercise.

In a typical quiz, the instruction is the question to the user.

A typical use case in the content of a quiz would be that the instruction contains the verb which has to be conjugated by the student.

This is never used for a technical or usage instruction like "click there", "use your pen" or how to solve a certain type of quiz. The user interface of the app or the design of the book is fully responsible for explaining how to use a quiz or exercise in a paperback book. That is never part of the content of a Bit.

bitmark	Description, Example
`[!...]`	Instruction, bitmark--, if declared as text format by the type
	Do `[_Versprich][!versprechen] mir bitte, dass du das nächste Mal daran denkst!` ➔ __________ (versprechen) mir bitte, dass du das nächste Mal daran denkst!
	*Don't ever* `... [!Use your pen to underline the correct answer.] ...`

We strongly belief that information contained in bitmark JSON should be platform/medium/device/channel independent.

Hint [?...]

Hints are hidden and only shown upon user request (for example by clicking a help button).

A hint must be related to solving the quiz and should reduce the complexity of the quiz by giving additional help.

Like the instruction, the hint must not be related to the usability or to a certain device in any way.

Hints must not be necessary to solve the quiz.

bitmark	Description, Example
`[?...]`	Hint, bitmark--
	Do `Hast du [_den][?der Film; Akkusativ] Film gesehen?` ➔ Hast du _____ (?) Film gesehen?
	Don't `...[?Strike trough the incorrect answers using your pen.] ...`

Sample Solution [@sampleSolution:...]

Sample solution is used for feedback after the user sent in his solution. They can also be used as input for more advanced feedback systems (for example for AI driven solutions that give didactically valuable feedback).

A sample solution must not be related to the usability or to a certain device in any way.

bitmark	Description, Example
`[@sampleSolution:...]`	Sample Solution, bitmark++

[@sampleSolution:

The followong curve shows the simple solution:

|image:https://example.com/solution.png|

]

Example [@example]

If @example is present, the app should display the solution of this part of the quiz as it would have been correctly solved by the user. This is used to show an example of a solution for a better understanding of the quiz.

[@example: This is an example for a solution] or its short form [@example] when chained to the solution of a quiz.

@example supports bitmark--, if declared. This should be used to make the example solution even more obvious to the user.

Users must not be able to change examples.

[@example: This is an example of a solution with an **important** part.]

See cloze-instruction-grouped for an example.