Aktuellt

Dokumentera ditt arbete

Todo och changelog

För att dokumentera ditt arbete ska du upprätthålla två filer skrivna i språket Markdown, todo.md och changelog.md.

Todo.md och changelog.md ska placeras i rotmappen (rotkatalogen) för projektet, i praktiken innebär det att de ska ligga i översta nivån i din www-mapp.

todo.md

Todo.md är en helt enkelt en att-göra-lista. Du kan göra den som en lista med kryssrutor (som jag brukar föredra) eller bara som en vanlig punktlista där du stryker saker allt efersom de blir klara.

En punktlista i MD (Markdown) gör du helt enkelt genom att sätta ett bindestreck (-) eller en asterisk (*) plus ett mellanslag framför raden i listan. Genomstruken text i MD gör du genom att sätta tecknet tilde (~) före och efter texten som ska vara genomstruken (exempel på genomstruken text ).

En kryssruta gör du genom att skriva hakparenteser, med ett mellanslag mellan efter "punkten" i listan ([ ]). En markerad kryssruta skriver du ett "x" i: [x].

changelog.md

Changelog.md är projektets loggbok. Här antecknar du allt arbete du gör med sajten. Använd datum som rubrik, datumet ska vara skrivet enligt ISO-standard, det vill säga precis som vi brukar skriva datum i Sverige: år-månad-dag (åå-mm-dd eller åååå-mm-dd).

Varför?

Systemet med changelog och todo är, med variationer, mycket vanligt i alla typer av kodprojekt. Fördelar som kan nämnas är att det blir enkelt för människor att samarbeta om alla kan se vad som behöver göras och vad som är gjort. Att på ett enkelt sätt ha koll på detta med hjälp av enkla textfiler är naturligtvis en stor fördel även om du är ensam i projektet.

I kursen använder jag din changelog och todo för att kunna följa ditt arbete.

Det är enkelt att skriva dina egna filer från scratch, men om du vill har jag också förberett en mall för todo och en mall för changelog som du kan använda.

Språket Markdown

Vad är Markdown?

Markdown är ett mycket förenklat markupspråk. Idén är att det ska vara ett mycket lättskrivet språk som dessutom kan översättas till HTML. Samtidigt med språket skapades det första programmet för att producera HTML från Markdown.

Språket (och programmet) hittades på 2004 av John Gruber, mannen bakom bloggen Daring Fireball, och Aaron Swartz.

Idéen var att hitta på ett textformat som är så lätt som möjligt för människor att läsa, samtidigt som det enkelt skulle kunna omvandlas till HTML för publicering på webben. Formatet påminner alltså om hur människor tidigare markerat text i enkla textdokument där man inte kan ändra bokstävernas utseende, men mer standardiserat.

Var används Markdown?

Överallt! Men framförallt är en stor del av allt innehåll på GitHub och GitLab skrivet i MD. Eftersom framför allt GitHub, men på senare tid också GitLab, har blivit de främsta platserna för utveckling av mindre och medelstora kodprojekt har det blivit en de facto-standard att skriva dokumentation i MD.

Hur skrivs Markdown?

Markdown har en mycket enkel syntax. Enkelt kan det beskrivas som ett enkelt textdokument (kodat som utf-8) där rubriker och annat märks ut med ett eller flera tecken innan raden. En rubrik motsvarande HTML:s <h1>Rubrik</h1> skrivs helt enkelt: # Rubrik. Ett nummertecken först i raden helt enkelt. Syns tydligt, är begripligt för ett datorprogram och hindrar inte läsning av människor.

Det som markerar att det är ett markdown-dokument och inte ett .txt-dokument vilket som helst är att det ges filändelsen .md i stället för .txt. Ingen <!DOCTYPE> eller liknande behövs, det är bara att skriva.

Det finns ett flertal olika sajter med instruktioner för hur man skriver, jag tycker att den här är bra: Markdown-Cheatsheet.

Som du kan se, kan du ofta skriva på lite olika sätt utan att det blir fel. Det är också väldigt enkelt och du kan snabbt hävda att du behärskar ytterligare ett kodspråk 😉!