diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..5cf38d58f55033b71893d621566ffa95ee552bcc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,165 @@
+# 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](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](src/fi/jyu/mit/gui/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](src/fi/jyu/mit/gui/TextAreaOutputStream.java)
+    - [​TextAreaWriter.java](src/fi/jyu/mit/gui/TextAreaWriter.java)
+
+### 1.5 StringTable yms.
+
+- alustava [​StringTable](src/fi/jyu/mit/gui/StringTable.java) - luokka
+     - ks käyttömalli: [​StringTableSuunniteltuKayttotapa](src/fi/jyu/mit/gui/example/StringTableSuunniteltuKayttotapa.java)
+     - 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](src/fi/jyu/mit/gui/ObjectTable.java), johon voi tallentaa olioviitteen jokaisen solun kohdalle halutessaan.
+  ks käyttömalli: [​ObjectTableSuunniteltuKayttotapa](src/fi/jyu/mit/gui/example/ObjectTableSuunniteltuKayttotapa.java)
+
+## 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:
+
+```java
+    /**
+     * 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:
+
+```java
+    /**
+     * 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: 
+
+```java
+    /**
+     * 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.
+
+```java
+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ä
+
+```java
+  kerho.add(uusiJasen);
+  listJasenet.add(uusiJasen.getNimi(),uusiJasen); 
+```