Kehittäjät Miksi sinun ei pitäisi ohittaa dokumentaatiota

Mobiilisovellusten, verkkosovellusten, työpöytäsovellusten tai JavaScript-kirjastojen kehitysalueella dokumentoinnilla on tärkeä rooli, joka voisi määrittää ohjelmiston kehitystyön. Mutta jos olet koskaan tehnyt asiakirjoja, olisit samaa mieltä kanssani siitä, että kehittäjille on melko vähiten suosikki asioita.

Toisin kuin kirjoituskoodi (jota kehittäjät ovat allekirjoittaneet), dokumentaation (jota emme ole tehneet) on oltava ja ne pitäisi helposti sulattaa jokainen. Teknisesti meidän on käännettävä konekieli (koodi) ihmiselle ymmärrettäväksi kieleksi, joka on kovempaa kuin se kuulostaa.

Vaikka se voi olla todellista rasitusta, asiakirjojen kirjoittaminen on tärkeää ja tarjoaa etuja käyttäjillesi, työtovereillesi ja erityisesti itsellesi.

Hyvä dokumentaatio auttaa käyttäjiä

Dokumentaatio auttaa lukijaa ymmärtää, miten koodi toimii, tietenkin. Mutta monet kehittäjät tekevät virheen olettaen, että ohjelmiston käyttäjät ovat taitavia. Näin ollen dokumentaatio voi olla ohut materiaali, joka ohittaa paljon olennaisia seikkoja, jotka sen olisi pitänyt sisältyä alusta alkaen. Jos olet taitossa kielellä, voit selvittää asioita omasta aloitteestasi; jos et ole, niin olet kadonnut.

Käyttäjille tarkoitettu dokumentaatio koostuu tavallisesti käytännöllisestä käytöstä tai “miten”. Nyrkkisääntö yleisten käyttäjien dokumentaation luomisessa on se sen pitäisi olla selkeä. Ihmisystävällisten sanojen käyttäminen on parempi kuin tekniset termit tai kieli. Myös todelliset käyttöesimerkit arvostetaan suuresti.

Hyvä ulkoasusuunnittelu auttaisi käyttäjiä myös skannaamaan jokaisen dokumentointiosan ilman silmien rasitusta. Muutamia hyviä esimerkkejä (nimeltään suosikkini) ovat Bootstrapin ja WordPressin dokumentaatio “Ensimmäiset vaiheet WordPressin avulla”.

Se auttaa muita kehittäjiä

Jokaisella kehittäjällä on oma koodaustyyli. Mutta kun on kyse tiimissä työskentelystä, meidän on usein jaettava koodit muiden joukkueiden kanssa. Joten se on välttämätöntä olla yksimielisiä standardista pitää kaikki samalla sivulla. Asianmukaisesti kirjoitettu dokumentaatio olisi viitoitus joukkueen tarpeisiin

Toisin kuin loppukäyttäjän dokumentaatio, tämä dokumentaatio kuvailee yleensä tekniset menettelyt kuten koodin nimeämiskäytäntö, jossa näytetään, kuinka tiettyjä sivuja tulisi rakentaa, ja miten API toimii yhdessä koodin esimerkkien kanssa. Usein meidän olisi myös kirjoitettava dokumentit sisäisen koodin kanssa kommentit) kuvaamaan, mitä koodi toimii.

Lisäksi siinä tapauksessa, jossa olet uusia jäseniä joukkueesi myöhemmin, tämä dokumentaatio voisi olla aika tehokas tapa kouluttaa heitä, joten sinun ei tarvitse antaa heille 1-on-1-koodia.

Kummallista se auttaa myös kooderia

Hauska juttu koodauksesta on joskus jopa kehittäjät itse eivät ymmärrä koodia, jonka he ovat kirjoittaneet. Tämä pätee erityisesti tapauksissa, joissa koodit on jätetty koskematta kuukausia tai jopa vuosia.

Äkillinen tarve tarkistaa koodit toisesta tai toisesta syystä jättää yhden ihmettelemään, mitä heidän mielissään oli, kun he kirjoittivat nämä koodit. Älä ole yllättynyt: olen ollut tässä tilanteessa. Tämä on tarkasti kun minä halusi Olin dokumentoinut koodin oikein.

Dokumentoimalla koodisi, voit päästä koodien alaosaan nopeasti ja turhautumatta, jolloin säästät paljon aikaa, joka voidaan käyttää muutosten tekemiseen.

Mikä tekee hyvää dokumentaatiota?

Hyvää dokumentaatiota on useita tekijöitä.

1. Älä koskaan oleta

Älä oleta, että käyttäjät tietävät mitä sinä tietää sekä mitä ne haluavat tietää. Se on aina parempi aloittaa alusta alkaen käyttäjien pätevyystasosta riippumatta.

Jos esimerkiksi rakensit jQuery-laajennuksen, voit ottaa inspiraation SlickJS: n dokumentaatiosta. Se näyttää, miten HTML-tiedostojen rakenne, missä CSS ja JavaScript voidaan sijoittaa, miten jQuery-laajennuksen alustus voidaan aloittaa, ja jopa näyttää täydellisen lopullisen merkinnän kaikkien näiden tavaroiden lisäämisen jälkeen, mikä on jotain ilmeistä.

Alarivi on, että dokumentaatio on kirjoitettu käyttäjän, ei kehittäjän, ajattelun avulla. Lähestymällä omaa dokumentointiasi tällä tavalla saat paremman näkökulman oman teoksen järjestämiseen.

2. Seuraa standardia

Lisäämällä koodiin liittyvää dokumentaatiota, käyttää kielestä odotettua standardia. Jokainen toiminto, muuttujat ja funktion palauttama arvo on aina hyvä idea. Tässä on esimerkki hyvistä inline-dokumenteista PHP: lle.

 / ** * Lisää mukautettuja luokkia kehon luokkiin. * * @param array $ class Rungon osat. * @return array * / function body_classes ($ class) // Lisää ryhmän blogin blogeihin, joissa on enemmän kuin yksi julkaistu kirjoittaja. jos (is_multi_author ()) $ class [] = 'ryhmä-blogi';  palauta $ class;  add_filter ('body_class', 'body_classes');

Seuraavassa on muutama viittaus inline-dokumentaation muotoiluun parhaiden käytäntöjen avulla PHP: ssä, JavaScriptissä ja CSS: ssä:

PHP: PHP-dokumentointistandardi WordPressille
JavaScript: UseJSDoc
CSS: CSSDoc

Jos käytät SublimeText-ohjelmaa, suosittelen asentamaan DocBlockrin, joka koodaa ennakkoluulottomasti inline-dokumentaatiolla.

3. Graafiset elementit

Käytä graafisia elementtejä, he puhuvat paremmin kuin teksti. Nämä tiedotusvälineet tulevat hyödyllisiksi, varsinkin jos luot ohjelmiston graafisella käyttöliittymällä. Voit lisätä osoittavia elementtejä, kuten nuolia, ympyrää tai mitään, mikä voi auttaa käyttäjiä selvittämään, mistä mennä suorittamaan vaiheet, ilman arvailua.

Seuraavassa on esimerkki Tower-sovelluksesta, jossa voit tehdä inspiraatiota. Ne selittävät tehokkaasti, miten versionhallinta toimii miellyttävällä tavalla, mikä tekee siitä ymmärrettävämmän kuin pelkkä tekstikomentorivien käyttö.

4. Leikkaus

Voit harkita muutamia asioita pakkausluetteloissa ja taulukoissa asiakirjoihin, koska tämä helpottaa sisällön skannaamista ja lukemista käyttäjille.

Lisää sisältöä koskeva taulukko ja jaa dokumentaatio helposti sulaviin osiin, mutta pidä kukin osio tärkeänä seuraavaksi. Pidä se lyhyt ja suoraviivainen. Alla on esimerkki hienosti järjestetystä dokumentaatiosta Facebookissa. Sisällysluettelo vie meidät mihin haluat siirtyä napsautuksella.

5. Tarkenna ja päivitä

Lopuksi, tarkista asiakirjat virheistä ja tarkista tarvittaessa tai aina, kun tuotteeseen, ohjelmistoon tai kirjastoon tehdään merkittäviä muutoksia. Asiakirjat eivät olisi hyödyksi kenellekään, jos sitä ei päivitetä säännöllisesti tuotteen mukana.