diff --git a/doc/functions.md b/doc/functions.md
index 6c8e38c..7d32369 100644
--- a/doc/functions.md
+++ b/doc/functions.md
@@ -92,6 +92,8 @@
 * `shuffle args` – tasuje elementy `args`:
 	- `args` – powinna być to tablica;
 
+* `sim` – #TODO
+
 * `sort args` – sortuje elementy `args`:
 	- `args` – powinna być to tablica;
 
diff --git a/doc/wprowadzenie.md b/doc/wprowadzenie.md
index 77ca285..d8e8bdd 100644
--- a/doc/wprowadzenie.md
+++ b/doc/wprowadzenie.md
@@ -6,10 +6,9 @@ author: Robert Bendun <robben@st.amu.edu.pl>
 
 # Wprowadzenie do języka Musique
 
-W poniższej dokumentacji obowiązują następujące konwencje:
+W dalszej części tekstu przyjmujemy następujące konwencje:
 
-`>` jest to [znak zachęty](https://pl.wikipedia.org/wiki/Znak_zach%C4%99ty) i wskazuje gotowość programu Musique do wprowadzania tekstu.
-Indykuje on obecność w sesji programu Musique.
+`>` – jest to [znak zachęty](https://pl.wikipedia.org/wiki/Znak_zach%C4%99ty) i wskazuje gotowość programu Musique do wprowadzania tekstu. Jeżeli widzisz taki znak, oznacza to, że jesteś w programie Musique.
 
 Przykładowo:
 
@@ -19,12 +18,12 @@ Przykładowo:
 >
 ```
 
-prezentuje efekt wpisania tekstu `3 + 4` oraz potwierdzenia przyciskiem `ENTER`, na co Musique zareagowało wynikiem tej operacji.
+W tym przykładzie wykonujemy `3 + 4` , zatwierdzając ENTERM, w zwrocie otrzymując – w tym konkretnym przypadku – wynik operacji.
 
-Jeśli przykład terminala nie przedstawia interaktywnej sesji, a zawartość pliku to znak zachęty nie występuje na początku linii.
-Nie ma różnic pomiędzy wykonywaniem komend języka Musique z pliku lub z sesji interaktywnej, różnią się tylko wygodą użytkownika.
+Nawiasem mówiąc – przykłady w tym wprowadzeniu mogą rozpoczynać się od `>` – oznacza to, że polecenia wprowadzono w sesji interaktywnej, lub bez tego znaku – wtedy traktujemy przykład jako zapisany plik z poleceniami.
+Nie ma różnic pomiędzy wykonywaniem poleceń języka Musique zawartych w pliku, a poleceniami wprowadzanymi w sesji interaktywnej – wybór pozostawiamy użytkownikowi.
 
-Można wykonać polecenia rozpisane na kilka linijek w sesji interaktywnej - należy wtedy wpisać je w formie jednej linii.
+Można wykonać złożone polecenia (które w pliku rozstałby rozbite na kilka linii) w sesji interaktywnej - należy wtedy wpisać je w formie jednej linii.
 
 ## Nuty, pauzy, akordy
 
@@ -44,7 +43,7 @@ Możesz zagrać inną nutę jak E:
 > play e
 ```
 
-lub wiele nut rozdzielając je przecinkiem:
+lub wiele nut po kolei – należy umieścić je w nawiasach okrągłych, rozdzielone przecinkami:
 
 ```
 > play (c, e, g)
@@ -61,15 +60,15 @@ pozwala to przykładowo tworzyć:
 - `c##` - dźwięk d
 - `eb` - dźwięk dis
 
-Aby dźwięk został odtworzony w odpowiedniej oktawie można podać ją zaraz przy dźwięku - `c4` to dźwięk c w 4 oktawie, `c#8` to dźwięk cis w 8 oktawie.
+Aby dźwięk został odtworzony w wybranej oktawie można dołączyć do znaku dźwięku liczbową wartość oktawy - `c4` to dźwięk c w 4 oktawie, `c#8` to dźwięk cis w 8 oktawie, itp.
 
 ```
 > play (c4, c5, c6)
 ```
 
-Aby dźwięk trwał określoną długość należy podać jako parametr pożądaną długość:
+Aby dźwięk trwał określoną długość należy podać jako dodatkowy parametr pożądaną wartość, przykładowo:
 
-Sekwencja złożona z: ćwierćnuty c w 4 oktawie, półnuty d w 5 oktawie oraz całej nuty e w 4 oktawie wygląda następująco:
+Sekwencja złożona z dźwięku C w 4 oktawie trwającym ćwierćnutę, dźwięku D w 5 oktawie trwającym półnutę oraz dźwięku E w 4 oktawie trwającym całą nutę wygląda następująco:
 
 ```
 > play (c4 (1/4), d5 (1/2), e4 1)
@@ -91,7 +90,7 @@ Można zapis uprościć korzystając z predefiniowanych czasów dźwięków:
 | `dsn` | szesnastka z kropką | `3/32` |
 | `tn` | trzydziestkadwójka | `1/32` |
 
-Korzystając z tych długości możemy uprościć powyższy przykład:
+Korzystając z tych długości możemy powyższy przykład zapisać równoważnie w ten sposób:
 
 ```
 > play (c4 qn, d5 hn, e4 1)
@@ -99,7 +98,7 @@ Korzystając z tych długości możemy uprościć powyższy przykład:
 
 ### Pauzy
 
-Pauzy stosuje się poprzez zastąpienie nazwy dźwięku literą `p`.
+Pauzy stosuje się poprzez użycie litery `p`:
 
 ```
 > play (c4 hn, p qn, c4 hn, p qn, c4 hn)
@@ -107,13 +106,13 @@ Pauzy stosuje się poprzez zastąpienie nazwy dźwięku literą `p`.
 
 ### Akordy
 
-Aby odegrać akord należy umieścić sekwencję dźwięków na niego się składających w wywołaniu funkcji `chord`:
+Aby odegrać akord należy umieścić symbole dźwięków, z których miałby się składać, w wywołaniu funkcji `chord`:
 
 ```
 > play (chord (c, e, g))
 ```
 
-W utworze możemy chcieć częściej używać tych samych akordów bądź sekwencji dźwięków. Możemy zachować je pod nową nazwą:
+W utworze możemy chcieć częściej używać tych samych akordów czy sekwencji. Przypisanie ich do wybranej nazwy wyglądałoby tak:
 
 ```
 > sekwencja := (c, e, g)
@@ -121,9 +120,9 @@ W utworze możemy chcieć częściej używać tych samych akordów bądź sekwen
 (c, e, g)
 ```
 
-(wpisanie samego wyrażenia takiego jak nazwa pozwala zobaczyć jej zawartość).
+Wpisanie samej nazwy pozwala zobaczyć co się pod nią znajduje.
 
-Z utworzonej sekwencji możemy stworzyć akord:
+Zapisaną sekwencję możemy przerobić na akord, ponownie wykorzystując funkcję `chord`:
 
 ```
 > C := chord sekwencja
@@ -137,7 +136,7 @@ i następnie go odtworzyć:
 > play C
 ```
 
-należy zwrócić uwagę, że Musique rozróżnia wielkość liter. Ponadto nazw będących oznaczeniami dźwięków jak `c` bądź `cffff` nie można używać jako nazw dla zmiennych.
+Należy zwrócić uwagę, że Musique rozróżnia wielkość liter. Ponadto nazw będących oznaczeniami dźwięków jak `c` bądź `cffff` nie można używać jako nazw dla zmiennych.
 
 ## Metody tworzenia sekwencji
 
@@ -169,13 +168,15 @@ Funkcja `pick` pozwala na wybór losowego elementu z sekwencji. Można użyć je
 > play (c4 (pick qn hn))
 ```
 
+W powyższym przykładzie dźwięk C w oktawie 4 zostanie zagrany losowo z długością ćwierćnuty lub półnuty.
+
 ### Losowe ustawienie elementów sekwencji
 
 Funkcja `shuffle` pozwala na tworzenie sekwencji z losową kolejnością elementów, np:
 
 ```
 > shuffle (c, e, f, g)
-(c, g, e, f)
+(f, g, e, c)
 ```
 
 ### Generowanie sekwencji w oparciu o liczbę półtonów
@@ -187,7 +188,7 @@ Funkcja `shuffle` pozwala na tworzenie sekwencji z losową kolejnością element
 (c4, c#4, d4, d#4)
 ```
 
-lub krócej wykorzystując funkcję `up`.
+Podobny efekt można uzyskać funkcję `up` jako generator wartości liczbowych:
 
 ```
 > up 5
@@ -197,7 +198,7 @@ lub krócej wykorzystując funkcję `up`.
 > play (c4 + up 4)
 ```
 
-lub jeśli chcemy zagrać w odwrotnej kolejności funkcję `down`:
+Analogicznie działa funkcja `down`, generująca wartości liczbowe w kierunku zera:
 
 ```
 > down 5
@@ -207,7 +208,7 @@ lub jeśli chcemy zagrać w odwrotnej kolejności funkcję `down`:
 > play (c4 + down 5)
 ```
 
-możemy złączyć sekwencje przy pomocy operatora `&`:
+Możemy złączyć sekwencje przy pomocy operatora `&`:
 
 ```
 > up 5 & down 5
@@ -215,7 +216,7 @@ możemy złączyć sekwencje przy pomocy operatora `&`:
 > play (c4 + up 5 & down 5)
 ```
 
-jeśli przeszkadza nam podwójnie zagrana nuta `e4` możemy ją wyeliminować funkcją `uniq` która usuwa sąsiadujące ze sobą duplikaty:
+Jeśli przeszkadza nam podwójnie zagrana nuta `e4` możemy ją wyeliminować funkcją `uniq`, która usuwa sąsiadujące ze sobą powtórzenia:
 
 ```
 > uniq (up 5 & down 5)
@@ -223,26 +224,29 @@ jeśli przeszkadza nam podwójnie zagrana nuta `e4` możemy ją wyeliminować fu
 > play (c4 + uniq (up 5 & down 5))
 ```
 
-
 ## Metody odtwarzania sekwencji
 
-Musique posiada trzy główne metody otwarzania sekwencji:
+Musique posiada trzy główne metody odtwarzania sekwencji:
 
-- `play` które odtwarza kolejne dźwięki po kolei
+- `play` które odtwarza dźwięki w kolejności
 - `par` które odtwarza pierwszy dźwięk równocześnie z pozostałymi
 - `sim` który odtwarza każdą podaną mu sekwencję równocześnie
 
-Każda z nich w momencie napotkania dźwięku z nieokreśloną oktawą lub długością
-wypełni tą wartość według wartości *domyślnej* (wartości domyślne to: 4 oktawa, 120 bpm, ćwierćnuta).
+Każda z nich w momencie napotkania dźwięku z nieokreśloną oktawą lub długością wypełni ją według wartości *domyślnej* (wartości domyślne to: 4 oktawa, 120 bpm, ćwierćnuta).
 
-Wartości domyślne można ustawiać przy pomocy funkcji `oct`, `len` oraz `bpm`.
+Wartości domyślne można ustawiać przy pomocy funkcji `oct`, `len` oraz `bpm`. Poniższy przykład ustawia domyślną oktawę na 5, domyślną długość na półnutę oraz domyślne tempo na 100 uderzeń na minutę:
+
+```
+> oct 5
+> len hn
+> bpm 100
+```
 
 ### `play`
 
-`play` przechodzi kolejno przez kolejne elementy sekwencji. `play` kończy wykonanie po odtworzeniu
-wszystkich dźwięków na niego się składających.
+`play` przechodzi kolejno przez elementy sekwencji i kończy się po odtworzeniu wszystkich dźwięków.
 
-Jeśli chcemy wykonać kilka `play` po sobie, możemy to osiągnąć rozdzielając je przecinkami - identycznie jak wcześniej tworzone sekwencje:
+Jeśli chcemy wykonać kilka `play` po sobie, możemy to osiągnąć rozdzielając je przecinkami – analogicznie do wspomnianych wcześniej sekwencji:
 
 ```
 play (c qn, e qn, g hn),
@@ -250,7 +254,9 @@ play (16 * (f sn)),
 play (c qn, e qn, g hn),
 ```
 
-można zapisać prościej poprzez:
+Uwaga – powyższy przykład reprezentuje polecenia zapisane w pliku (stosujemy konwencję rozszerzenia `.mq`) – wskazuje na to brak znaku zachęty `>`.
+
+Można ten zapis uprościć:
 
 ```
 play (
@@ -260,16 +266,13 @@ play (
 ),
 ```
 
-gdzie wcięcia i entery zostały dodane dla poprawy czytelności.
+gdzie wcięcia i nowe linie zostały dodane dla poprawy czytelności.
 
 ### `par`
 
-`par` umożliwa wykonanie pierwszego argumentu przez całą długość trwania pozostałych -
-niezależnie od tego jak dźwięk został określony zostanie dopasowany do drugiej części.
+`par` umożliwa wykonanie pierwszego argumentu przez całą długość trwania pozostałych - niezależnie od tego jaka długość dźwięku została określona dla pierwszego z nich, zostanie dopasowany do sumy długości pozostałych dźwięków.
 
-Przykład inspirowany Odą do Radości, w którym akord trwa przez całą długość odtwarzania
-sekwencyjnie pozostałych dźwięków. Wcześniej ustawiamy domyślną oktawę jako piątą,
-by nie musieć powtarzać jej przy każdym dźwięku:
+Przykład inspirowany Odą do Radości, w którym akord trwa przez całą długość odtwarzania sekwencyjnie pozostałych dźwięków. Wcześniej ustawiamy domyślną oktawę jako 5, by nie musieć powtarzać jej przy każdym dźwięku:
 
 ```
 oct 5,
@@ -278,15 +281,15 @@ par (chord c3 g3 c4) (e, e, f, g)
 
 ### `sim`
 
-`sim` umożliwia wykonywanie równocześnie kilku sekwencji:
+`sim` umożliwia wykonywanie równocześnie kilku sekwencji.
 
-Brutalna metoda stworzenia akordu poprzez równocześne odtworzenie dźwięków c, e, g:
+Poniżej "niepoprawna" metoda stworzenia akordu poprzez równocześne odtworzenie dźwięków c, e, g:
 
 ```
 > sim c e g
 ```
 
-Trzy ćwierćnuty c4 oraz równocześnie po ćwierćnutowej pauzie 4 szesnastki d5:
+Trzy dźwięki C w domyślnej oktawie o długości ćwierćnuty odtwarzane równocześnie wraz z pauzą ćwierćnutową i czterema dźwiękami D w piątek oktawie o długości szesnastki:
 
 ```
 > sim (3 * c qn) (p qn, 4 * (d5 sn))