Sen olisi sisällettävä kaikki seikat, jotka kehittäjän on tiedettävä ja joita ei voi saada suoraan kehittäjältä. koodi. Näihin kuuluvat kehitystoimet ja -kiellot, täydelliset käyttöönotto-ohjeet, ulkoisen integroinnin kuvaukset ja niin edelleen. Tämä viesti opastaa sinua luomaan tehokkaan, kauniin ja luettavan README-tiedoston omaan projekti.

Hyvin valmisteltua projektidokumentaatiota varten löytyy hyvä johdanto github-oppaista: https://guides.github.com/features/wikis/. Siinä sanotaan, että "README:n tulisi sisältää vain tarpeelliset tiedot, jotta kehittäjät voivat aloittaa projektin käytön ja siihen osallistumisen".

Tässä mielessä esittelemme luettelon osatekijöistä ja parhaista käytännöistä, joita Codestissa noudatetaan projektidokumentaation luomisessa.

Pikaesittely

- Hankkeen nimi: tämä on pakollinen osa jokaista README-tiedostoa.

- Tilamerkit: Jos käytät ulkoisia koodin laadun mittauksia, automaattista testausta tai muita työkaluja, asiakirjan alussa on hyvä paikka näyttää muille, toimivatko ne.

- Kuvaus: sisällytä muutama lause hankkeesta, jotta voit kuvailla nopeasti sen päätarkoitusta ja toimintaa.

Sisällysluettelo

Sisällysluettelo voi olla hyödyllinen pitkille dokumentaatiotiedostoille, mutta jos README-tiedostosi on melko tiivis, se ei ole tarpeen.

Yleisiä tietoja

- Tietoja-osio: Tämän pitäisi olla yksityiskohtaisempi kuvaus projektista - se voi sisältää tietoja käyttäjistä, heidän rooleistaan, joitakin hämmentävämpiä tapauksia, kuvakaappauksia jne.

- Mockupit: paikka, jossa on linkkejä UI/UX-mockup-resursseihin, jos sellaisia on.

• Muut tiedot, kuten Pääsy palvelimille tai Integrointi ulkoisten API:iden kanssa: esimerkkeinä voidaan mainita staging-instanssin url-osoite, jaetut ei-sensitiiviset (!) käyttöoikeustiedot, linkit dokumentaatioon, joitakin ohjeita jne.

Asennus

- Vaatimukset: ennakkoedellytykset, jotka on täytettävä ennen sovelluksen asennuksen aloittamista, esim. ulkoisten työkalujen asennus.

- Asetukset: vaiheittainen ohje, jota noudattamalla projekti saadaan käyntiin.

- Asetukset: kuvaavat, minne paikalliset asetukset tallennetaan, ja antavat ohjeet omien asetusten vastaanottamisesta.

- Paikallinen kokoonpano: jos on joitakin tapauksia, jotka koskevat paikallisia asetuksia, tämä on hyvä paikka selitykselle.

Kehitys

Tämä osio on ihanteellinen paikka ohjeille, jotka koskevat esimerkiksi ominaisuuksien kehittämistä, bugikorjauksia, hotfixejä, yleisiä ominaisuuksia, testausta, tyylioppaita, koodin organisointia, muita projektissa käytettäviä kehitystyökaluja (esim. guardit tai dockerit) ja niin edelleen. Älä unohda mainita kaikkia sääntöjä, joita jokainen joukkue jäsenen tulisi tietää.

Käyttöönotto

Anna selkeät vaiheittaiset ohjeet kutakin ympäristöä varten ja kaikki se, mikä on "hyvä tietää" käyttöönottoa tehtäessä.

Muita ajatuksia erillisiä jaksoja varten

- API-dokumentaatio

- Muutosluettelo

- Ulkoiset resurssit: paikka kaikenlaisille linkeille, jotka voivat olla hyödyllisiä.

- Sovelluspino: luettelo projektissa käytettävistä sovelluspinoista - voi sisältää lyhyen kuvauksen ja palveluntarjoajan nimen.

Joukkue

On kiistanalaista, onko tarpeen näyttää projektiryhmän nykyiset jäsenet (github tarjoaa oletusarvoisesti täydellisen luettelon osallistujista), mutta on aina mukavaa, jos näet nimesi yhtenä projektin kirjoittajista. Jos teet näin, pidä se mahdollisimman ajantasaisena.

Viimeiset sanat

Muista, että jokainen hanke on ainutlaatuinen, ja niin on myös sen dokumentointi. README:n kirjoittamiseen ei ole olemassa yhtä ainoaa hyvää ratkaisua. Noudata vain yleisiä vinkkejä, ja tärkeintä on muistaa aina refaktorointi, joka liittyy myös README:hen. On aina hyvä tarkastella dokumenttia kokonaisuutena ja miettiä se uudelleen, jos jokin asia on esitettävä eri tavalla.

Vielä yksi asia: "ohjeet" ovat avainasemassa, joten kirjoita niitä paljon. Kiitos!

Lue lisää:

• Avoin-suljettu-periaate. Tarvitseeko minun koskaan käyttää sitä?
• Miten kirjoittaa hyvää ja laadukasta koodia?
• 1TP53Kalenteri. Uusi Codestin projekti, joka perustuu Vue.js:ään.