Markdown lab reports¶

Exercise markdown-lab-reports-annex.pdf · PDF

You finish a practical. To prove it, you take a photo of the screen with your phone — at an angle, with a reflection of the ceiling lights across the terminal. Can anyone copy the command from that photo? Search in it? Even read it?

A screenshot proves you were there. A report proves you understood. From now on, every practical in this course is handed in as a short report written in Markdown, always with the same template. Learn it once today and you will use it about thirty times this year — and in every software job after that, because the README of almost every project on the Internet is written the same way.

Why plain text?¶

Plain text is a file made only of characters — letters, digits, spaces, line breaks — with no hidden formatting.

Remember text as bytes from Unit 1: a plain-text file is exactly those bytes, nothing else. That gives it three superpowers:

What is Markdown?¶

Markdown is a way of writing plain text with a handful of ordinary characters — #, *, - — that a program turns into headings, bold, lists and code.

It was created in 2004 by John Gruber, with Aaron Swartz. The file is still plain text, with the extension .md. The README of almost every software project is a .md file. So is every page of this website — including this one.

flowchart LR
    SRC["<b>Source</b><br>marks.md<br>plain text with # and *"] -->|"a preview<br>renders it"| VIEW["<b>Preview</b><br>headings, bold,<br>lists, code"]
    SRC -->|"still readable<br>without any program"| YOU["<b>A person</b><br>with any editor"]

The six marks a report needs¶

You only need six today:

Here is a small file that uses all six. On the left the source you type, on the right what the preview shows:

# My first Markdown file

## What I know

Markdown is **plain text** with marks.

- It opens in any editor.
- It is small.

1. Write.
2. Preview.

The kernel version: `uname -r`.

```bash
free -h
```

More: [CommonMark](https://commonmark.org)

free -h

The four classic mistakes¶

This text has four mistakes. Can you spot them before reading on?

#My report

This word is **bold* and this is not.

-first item
- second item

```
uname -r

The end.

1. #My report — a space is missing after #, so it is not a heading.
2. **bold* — bold needs two asterisks on each side.
3. -first item — a space is missing after the hyphen, so it is not a list item.
4. The code block opens with three backticks and is never closed: everything after it turns into code.

Two more traps:

• The backtick ` is not the apostrophe '. On a Spanish keyboard it is the key to the right of P: press it, then the space bar.
• A heading or a list glued to the paragraph above it may not render. Leave an empty line before and after every heading, list and code block.

The report template¶

Every practical from now on uses this template. Copy it as it is and fill it in:

# Practical U.n — Title of the practical

- **Name:** Name Surname
- **Group:** DAM-1
- **Date:** DD/MM/YYYY
- **Machine:** classroom PC, class server, or the VM name

## Goal

One or two sentences: what had to be done, and why.

## Steps

### 1. What I did, in one line

```bash
the command I typed
```

```text
the output, copied from the terminal
(only the lines that matter)
```

What it means: one sentence in my own words.

### 2. The next step

(the same four parts)

## Problems

What went wrong, what I tried, what fixed it.
If nothing went wrong: "None".

## Check

How I know it works: the "Done when" of the
statement, with the proof.

## What I learned

Two or three sentences in my own words.
Not a list of commands.

## Sources

- Pages, manuals and people that helped me.
- If I used cs50.ai: what I asked.

What each part is for:

One step, done right¶

The weak spot is always the fourth part. Compare:

### 2. Kernel

```bash
uname -r
```

It shows the kernel.

### 2. Find the kernel version

```bash
uname -r
```

```text
7.0.0-15-generic
```

What it means: the kernel is Linux, version 7.0.0 — the part
of the OS that talks to the hardware. The distribution is Ubuntu.

The good one says what was done in the title, shows the real output, and explains it in a sentence of its own. (Your version number will differ: always paste your output.)

Text first, screenshots last¶

Commands and their output go into the report as text, copied from the terminal: select it, then Ctrl+Shift+C. Never retype output by hand, and never paste a picture of text.

A screenshot is only for when there is no text to copy — a window, an installer screen. Save it next to the report as practical-U.n-surname-1.png, upload it with the report, and link it:

![The virt-manager window with the new VM](practical-2.2-garcia-1.png)

The file name¶

Every report is called practical-U.n-surname.md: lower case, no spaces, no accents.

Practical 2.2 by Marta Garcia is practical-2.2-garcia.md. Why so strict? Your teacher downloads thirty files into one folder. Thirty files called report.md in one folder are one file.

You hand in the .md file on Google Classroom before the deadline. Late work gets 5 at most; more than 48 hours late gets 0.

Your first report¶

On the Exercise sheet you write a trial report about your own PC, called trial-report-surname.md, with three steps — one for each command you already know:

grep PRETTY_NAME /etc/os-release
uname -r
free -h

For each one: what you did, the command, the output copied as text, and one sentence of your own — for example "My PC runs Ubuntu, version ..." (the name of the distribution, not of the kernel). Then upload it to Classroom. Upload what you have, finished or not: a half report with the right name beats a perfect one left on the desktop.

Key takeaways¶

• A report proves you understood; a screenshot only proves you were there. Write it so someone else could repeat your work.
• Plain text opens anywhere, can be copied, searched and compared. Markdown (Gruber and Swartz, 2004) adds headings, bold, lists, code and links with ordinary characters; files end in .md.
• Six marks: # headings, **bold**, - list, 1. numbered, backticks for code, [text](link). Always a space after #, - and 1., and an empty line around blocks.
• Every practical uses the template: header (with the machine), Goal, Steps, Problems, Check, What I learned, Sources.
• Each step has four parts; the fourth — what it means, in your own words — gets the marks.
• File name: practical-U.n-surname.md, lower case, no spaces, no accents.

Quick check¶

Next: the machines you will document in every report from now on are not real — Virtualisation.