Näin kirjoitat selkeän README-tiedoston GitHub-projektille

GitHub-projektiin saapuva vierailija haluaa yleensä tietää kolme asiaa: mitä projekti tekee, sopiiko se hänen tarpeeseensa ja miten sen saa käyttöön. README-tiedoston tehtävä on vastata näihin kysymyksiin ilman, että lukijan täytyy tutkia lähdekoodia tai arvailla asennusvaiheita.

Hyvä README palvelee myös projektin tekijää. Kun käyttöönotto, tärkeimmät komennot ja tunnetut rajoitukset on kirjoitettu muistiin, työhön palaaminen onnistuu pitkänkin tauon jälkeen. Samalla samoihin kysymyksiin vastaamiseen kuluu vähemmän aikaa.

Selkeys syntyy ennen kaikkea tiedon järjestyksestä. Lukijalle kerrotaan ensin tarkoitus, sitten aloittamiseen tarvittavat asiat ja lopuksi täydentävät ohjeet.

Mikä README-tiedosto on?

README on projektin esittely- ja ohjetiedosto, jonka GitHub voi näyttää automaattisesti tietovaraston etusivulla. Tavallinen nimi on README.md, jossa tiedostopääte viittaa Markdown-muotoiluun.

Aloittelijalle helppo sijoituspaikka on projektin juurihakemisto eli sama taso, jolla projektin keskeiset kansiot sijaitsevat. GitHub tunnistaa README-tiedostoja myös .github– ja docs-hakemistoista. Jos tiedostoja on useita, näyttämiseen vaikuttaa GitHubin määrittelemä hakujärjestys. GitHubin README-ohje.

README kannattaa kirjoittaa jo projektin alkuvaiheessa. Ensimmäiseksi versioksi riittävät lyhyt esittely, toimiva käynnistysohje ja tieto työn keskeneräisyydestä. Sisältöä voi täydentää ominaisuuksien kehittyessä.

Aloita konkreettisella kuvauksella

Projektin nimi ei välttämättä kerro ulkopuoliselle mitään. Sen alle tarvitaan muutama lause, jotka selittävät käyttötarkoituksen ja kohderyhmän.

Kuvitteellisen Retkimuistio-sovelluksen esittely voisi kuulua näin:

Retkimuistio on selaimessa käytettävä sovellus retkikohteiden ja varustelistojen tallentamiseen. Se on tarkoitettu retkeilijälle, joka haluaa suunnitella seuraavan matkansa tiedot yhteen paikkaan.

Kuvaus kertoo heti, mitä käyttäjä voi tehdä. Ilmaisu ”monipuolinen ja moderni ratkaisu erilaisiin tarpeisiin” jättäisi asian avoimeksi.

Mainitse myös projektin luonne, jos se vaikuttaa odotuksiin. Harjoitustyö, kokeellinen kirjasto ja aktiivisesti ylläpidetty työkalu ovat erilaisia lähtökohtia.

Teknologiavalinnat voi esitellä tämän jälkeen. Ensimmäisen kappaleen kannattaa auttaa lukijaa arvioimaan projektin hyötyä.

Rajaa ominaisuuslista tärkeimpiin asioihin

Ominaisuuslista antaa nopean kuvan sisällöstä. Valitse siihen muutama toiminto, joilla on käyttäjälle selkeä merkitys.

Retkimuistion lista voisi olla seuraava:

• Retkikohteiden tallentaminen omilla muistiinpanoilla.
• Varustelistojen luominen eri vuodenaikoja varten.
• Suunnitelmien hakeminen kohteen nimellä.
• Valmiin pakkauslistan tulostaminen.

Pidä suunnitellut ominaisuudet erillään toteutetuista. Jos karttanäkymä on vasta ajatuksena, sijoita se jatkokehitystä käsittelevään kohtaan.

Myös rajaus voi olla hyödyllinen tieto. Jos sovellus toimii ainoastaan yhdellä laitteella eikä synkronoi tietoja, kerro se suoraan. Näin käyttäjä pystyy arvioimaan soveltuvuuden ennen asentamista.

Kerro vaatimukset ennen asennusohjeita

Asennus epäonnistuu helposti, jos tarvittavat työkalut tai ympäristön vaatimukset selviävät vasta kesken tekemisen.

Kirjaa tähän kohtaan projektin kannalta olennaiset edellytykset:

• Tuetut ohjelmointikielen tai suoritusympäristön versiot.
• Tarvittava paketinhallinta.
• Mahdollinen tietokanta.
• Ulkoisen palvelun käyttäjätili.
• Käyttöjärjestelmään liittyvät rajoitukset.

Anna versiot sen perusteella, mitä projekti tukee ja mitä olet kokeillut. Ilmaisu ”tarvitset uusimman version” vanhenee nopeasti eikä kerro myöhemmin, millaisessa ympäristössä ohjelma toimi.

Erota käyttäjän ja kehittäjän tarpeet. Valmiin asennuspaketin käyttäminen voi onnistua ilman työkaluja, joita lähdekoodista rakentaminen edellyttää.

Jos jokin vaatimus koskee vain yhtä ominaisuutta, mainitse myös tämä yhteys.

Kirjoita asennus vaihe vaiheelta

Asennusohjeen tulee edetä siinä järjestyksessä, jossa uusi käyttäjä suorittaa tehtävät. Aloita tiedostojen hankkimisesta ja jatka asetuksiin sekä käynnistämiseen.

Kuvitteellisen Node.js-projektin ohje voisi sisältää seuraavat komennot, jos ne vastaavat projektin todellista rakennetta:

cd retkimuistio
npm install
npm run dev

Ennen komentolohkoa kerrotaan, mistä projektin saa ja mihin se puretaan. Lohkon jälkeen selitetään, että ensimmäinen komento siirtyy projektikansioon, toinen asentaa riippuvuudet ja kolmas käynnistää kehityspalvelimen.

Älä jätä lukijaa arvailemaan seuraavaa vaihetta. Kerro, mistä käynnistyneen sovelluksen osoite löytyy ja mitä selaimessa pitäisi näkyä.

GitHubissa komentolohko muodostetaan kolmella gravismerkillä. Kielimääritys, kuten bash, auttaa koodin esittämisessä ja voi ottaa käyttöön syntaksivärityksen. GitHubin koodilohko-ohje.

Selitä asetukset ja ympäristömuuttujat

Moni sovellus tarvitsee asetuksia, joita ei voi päätellä asennuskomennoista. Näitä voivat olla palvelun osoite, tietokantayhteys tai ulkoisen rajapinnan tunniste.

Kerro jokaisesta tarpeellisesta asetuksesta:

• Asetuksen nimi.
• Sen käyttötarkoitus.
• Onko arvo pakollinen.
• Mistä käyttäjä saa oikean arvon.
• Onko käytössä oletusarvo.

Jos projekti käyttää .env.example-tiedostoa, selitä sen kopioiminen ja muokattavat kohdat. Pelkkä maininta ”täytä ympäristömuuttujat” ei auta käyttäjää, joka kohtaa projektin ensimmäistä kertaa.

Käytä esimerkeissä selvästi kuvitteellisia arvoja. Oikeat salasanat, käyttöavaimet tai asiakastiedot eivät kuulu julkiseen ohjeeseen.

Pidä asetusten nimet samoina dokumentaatiossa ja koodissa. Yhden merkin kirjoitusvirhe voi estää koko sovelluksen käynnistymisen.

Näytä ensimmäinen onnistunut käyttökerta

Asentamisen jälkeen lukija tarvitsee pienen tehtävän, jolla hän pääsee alkuun. Valitse esimerkki, joka tuottaa helposti tunnistettavan tuloksen.

Retkimuistiossa ensimmäinen käyttökerta voisi edetä näin:

1. Avaa sovelluksen etusivu.
2. Valitse uuden retken lisääminen.
3. Kirjoita nimeksi ”Viikonlopun metsäretki”.
4. Lisää varustelistaan juomapullo ja sadevaatteet.
5. Tallenna retki ja tarkista, että se näkyy luettelossa.

Tällainen esimerkki auttaa sekä oppimisessa että toiminnan tarkistamisessa.

Komentorivityökalussa näytä vastaavasti yksi tavallinen komento ja sen odotettu tulos. Kirjastossa esittele lyhyt koodiesimerkki, jonka voi suorittaa ilman laajaa taustatyötä.

Ensimmäisen harjoituksen kannattaa pysyä yksinkertaisena. Harvinaisemmat käyttötavat voidaan käsitellä erillisissä ohjeissa.

Tee Markdown-rakenteesta helposti silmäiltävä

READMEa luetaan usein etsimällä tiettyä vastausta. Kuvaavat otsikot, lyhyet kappaleet ja johdonmukaiset listat nopeuttavat tiedon löytämistä.

Markdownissa otsikot muodostetaan risuaidoilla, luettelot esimerkiksi yhdysmerkeillä ja linkit hakasulkeiden sekä sulkeiden avulla. GitHub muodostaa otsikoiden perusteella myös avattavan sisällysluettelon. GitHubin muotoiluohje.

Toimiva sisältöjärjestys voi olla:

• Projektin esittely.
• Keskeiset ominaisuudet.
• Vaatimukset ja asentaminen.
• Asetukset.
• Käyttöesimerkit.
• Ongelmatilanteet.
• Osallistuminen ja lisenssi.

Kuvakaappaus auttaa käyttöliittymän esittelyssä, kun se näyttää olennaisen näkymän. Lisää kuvalle kuvaava vaihtoehtoinen teksti ja varmista, ettei kuvassa näy yksityisiä tietoja.

Vältä koristeiden kasaamista alkuun. Lukijan pitäisi löytää projektin tarkoitus ilman pitkää selaamista.

Ohjaa ongelmatilanteissa eteenpäin

Hyvä vianmääritysosio alkaa todellisista havainnoista. Jos tietty virheilmoitus toistuu, kirjoita sen yhteyteen mahdollinen syy ja tarkistusohje.

Esimerkiksi ”käynnistys epäonnistuu” on liian laaja kuvaus. Tarkempi ohje kertoo, mitä ilmoitusta etsitään, missä vaiheessa se ilmestyy ja mikä asetus tarkistetaan.

Määritä myös paikka avun pyytämiseen. Se voi olla projektin Issues-osio tai muu ylläpitäjän valitsema kanava.

Pyydä virheilmoitukseen hyödylliset tiedot:

• Käytetty ohjelmaversio.
• Käyttöympäristö.
• Ongelman toistamiseen tarvittavat vaiheet.
• Odotettu ja toteutunut toiminta.

Näin seuraava keskustelu voi keskittyä ongelman ratkaisemiseen lähtötietojen keräämisen sijaan.

Kerro osallistumisesta ja lisenssistä

Jos projektiin saa ehdottaa muutoksia, selitä lyhyesti, miten osallistuminen aloitetaan. Voit pyytää avaamaan suuresta muutoksesta ensin keskustelun tai ohjata suoraan osallistumisohjeeseen.

Laajemmat kehityskäytännöt sopivat CONTRIBUTING.md-tiedostoon. GitHub osaa nostaa osallistumisohjeen esiin esimerkiksi muutosehdotuksia ja issueita avattaessa. GitHubin osallistumisohje.

Mainitse READMEssa myös projektin lisenssi ja linkitä varsinaiseen lisenssitiedostoon. Varmista, että ilmoitettu nimi vastaa tiedoston sisältöä. GitHub tarjoaa lisenssin lisäämiseen oman työnkulun. GitHubin lisenssiohje.

Ylläpitäjän yhteystiedoksi kannattaa valita kanava, jota todella seurataan. Älä lupaa vasteaikaa, jota projektissa ei pystytä noudattamaan.

Tarkista ohje uudesta lähtötilanteesta

README kannattaa testata kuin et tuntisi projektia ennestään. Hanki puhdas kopio ja etene ohjeen mukaan hyödyntämättä omassa ympäristössä valmiiksi olevia asetuksia.

Tarkista erityisesti komennot, tiedostonimet, linkit ja esimerkkitulokset. Jos jokin vaihe onnistuu vain muistisi avulla, lisää puuttuva tieto ohjeeseen.

Pyydä mahdollisuuksien mukaan myös toista ihmistä kokeilemaan käyttöönottoa. Hänen kysymyksensä paljastavat helposti kohdat, joita tekijä pitää itsestäänselvinä.

Päivitä README samassa yhteydessä, kun muutat asennusta, asetuksia tai käyttöä. Näin dokumentaatio seuraa projektin todellista toimintaa ja seuraava käyttäjä pääsee aloittamaan luotettavan ohjeen avulla.