diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..c2da7dbf740520d16d6498695eb56ab6668bf4d9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,153 @@
+# 1. fi.jyu.mit.gui -komponentit
+
+- Swingin ​gui-luokkia, joilla `List`, tukku `RadioButtoneita` ja `ComboBox` käyttäytyvät samalla tavalla.
+- [yksinkertainen käytööesimerkki](blob/main/src/fi/jyu/mit/gui/example/SimpleListExample.java)
+
+## 1.1 Käyttö
+
+- lataa ​gui.jar
+- käyttää voi joko kirjaston kautta tai jar-tiedostoa suoraan
+     - jar-tiedoston käyttö suoraan
+          - oikealla napilla Eclipsen projektin nimen päällä Properties
+          - Java Build Path/Libraries/Add External Jars
+          - etsi gui.jar
+     - käyttö kirjaston kautta
+          - tee itsellesi User Library nimeltä gui ohjetta mukaillen
+          - liitä projektiin User Library gui (tai gui16)
+- ota WindowBuilderissä lisättävien komponenttien (Palette) 
+  System-kohdasta Choose Component ja kirjoita tähän haluamasi luokan nimen alkua ja valitse haluamasi luokka
+- usein tuntuu valittavan että ei voi lisätä, mutta silti lisääntyy
+- jatkossa nämä lisätyt löytyvät Custom-kohdasta
+- valitsimissa voit Kohteet-kohdasta lisätä merkkijonoja suunnittelun aikana
+- voit myös ensin luoda StringListModel -komponentin ja täyttää sen
+  haluamallasi tavalla ja sitten lisätä tämän Model-ominaisuutena valitsimeen.
+
+## 1.2 Valitsimet
+
+- ListChooser, ComboBoxChooser, RadioButtonChooser ja CheckBoxChooser kaikki käyttäytyvät samalla tavalla (ks​AbstractChooser.java)
+    - suunnitteluaikana lista näkyvistä valinnoista laitetaan kohteet-ominaisuuteen (voi tarvita avata lisäominaisuudet Properties-ikkunasta).
+    - voidaan pyytää valittuja listan tai valitsemisjärjestyksessä
+    - voidaan pyytää listan mukainen 1. valittu tai valintajärjestyksen 1. valittu tai viimeksi valittu
+    - Valinta-otsikko voidaan sijoittaa mihin tahansa 4-ilmansuuntaan tai piilottaa.
+         - jos teksti laitetaan vaikka West, kannattaa komponentin alta ottaa getCaptionLabel
+           ja siihen laittaa vaikka borderiksi Empty border, joka jättää sopivasti tilaa tekstin ja valinta-komponentin väliin.
+    - alkion lisääminen listaan
+  
+          list.add(jono);
+- Listassa, RadioButton- ja CheckBox- valitsimessa rullaus valmiina
+- Listassa ja CheckBox-listassa voidaan valita montako maksimissaan saa valita (-1=kaikki).
+- kuhunkin jonoon voidaan liittää joku olio
+
+      list.add(jono,olio);
+tai
+
+      list.setObject(i,olio)
+
+## 1.3 EditPanel
+
+- ​EditPanel jossa on Label ja Edit samassa
+- undo/redo
+
+## 1.4 Tietovirrat
+
+- tietovirrat tekstikenttään tulostamiseksi (ks. esim naytaJasen).
+    - ​TextAreaOutputStream.java
+    - ​TextAreaWriter.java
+
+### 1.5 StringTable yms.
+
+- alustava ​StringTable - luokka
+     - ks käyttömalli: ​StringTableSuunniteltuKayttotapa
+     - kokeile:
+
+            java -cp gui.jar fi.jyu.mit.gui.example.StringTableSuunniteltuKayttotapa
+
+    - jos haluaa suunnitteluaikana laittaa jonoja, pitää ottaa komponentin alta getTable() ja sen ominaisuuksista muutella modelia.
+    - luokkaan tulee valmiiksi pystysuuntainen liuku
+    - jos haluaa vaakasuuntaisen liun, pitää ottaa komponentin alta getTable()
+      ja sen ominaisuuksista muutella lisäominaisuutta autoResizeMode (esim OFF).
+- oliomaisempi versio ​ObjectTable, johon voi tallentaa olioviitteen jokaisen solun kohdalle halutessaan.
+  ks käyttömalli: ​ObjectTableSuunniteltuKayttotapa
+
+## 1.6 Todo
+
+- tapahtumankäsittely Swingin omilla tavoilla. Nyt on ongelma kun tuolta "irtaannutaan".
+- vastaavanlainen StringGrid jota olisi helppo käyttää
+- dokumentit
+- testit
+
+# 2. KerhoSwing-esimerkki ListChooserilla
+
+## 2.1 Alustus
+
+Ei mitään ihmeellistä
+
+## 2.2 Alkio yhdelle listan jäsenelle
+
+Ei tarvita
+
+## 2.3 Listan tietojen täyttäminen
+
+Nyt kun listaan tarvitsee saada tieto, voidaan se tehdä esimerkiksi seuraavasti:
+
+    /**
+     * Suorittaa niiden jäsenten hakemisen, joiden valittu kenttä täyttää hakuehdon
+     * TODO: nyt haetaan vielä kaikki jäsenet
+     */
+    protected void hae() {
+        listJasenet.clear();
+
+        for (Jasen jasen : kerho) {
+            listJasenet.add(jasen.getNimi(),jasen); 
+        }
+    }
+
+## 2.4 Klikatun jäsenen tunnistaminen
+Aluksi listan klikkausmetodi on alustamisvaiheessa yhdistetty sopivaan aliohjelmaan:
+
+    /**
+     * Tämä alustaa valitut alueet käyttökuntoon.
+     */
+    public void alusta() {
+        ...
+        listJasenet.addSelectionChangeListener(new SelectionChangeListener() {
+            @Override
+            public void selectionChange(IStringListChooser sender) { naytaJasen(); }
+        });
+        ...
+    }
+
+Sitten kun klikkaus tapahtuu, otetaan klikattu jäsen ja näytetään vastaavat tiedot: 
+
+    /**
+     * Näyttää listasta valitun jäsenen tiedot
+     */
+    protected void naytaJasen() {
+        int ind = listJasenet.getSelectedIndex();
+        if (ind < 0) return;
+        jasenKohdalla = (Jasen)(listJasenet.getSelectedObject());
+        areaJasen.setText("");
+        PrintStream os = TextAreaOutputStream.getTextPrintStream(areaJasen);
+        tulosta(os, jasenKohdalla);    
+    }
+
+## 2.5 Uuden jäsenen lisäys
+
+Uuden jäsenen lisäys on melkein helpointa tehdä niin, että jäsen lisätään suoraan Kerhon kautta ja sitten täytetään JList tämän jälkeen kokonaan uudelleen.
+
+    public void uusiJasen() {
+        jasenKohdalla = new Jasen();
+        jasenKohdalla.rekisteroi();
+        jasenKohdalla.vastaaAkuAnkka();
+        try {
+            kerho.lisaa(jasenKohdalla);
+        } catch (SailoException e) {
+            JOptionPane.showMessageDialog(null,
+                    "Ongelmia lisäämisessä! " + e.getMessage());
+        }
+        hae(jasenKohdalla.getTunnusnro());
+    }
+mutta toisaalta voitaisiin myös tehdä
+
+  kerho.add(uusiJasen);
+  listJasenet.add(uusiJasen.getNimi(),uusiJasen);