18 Software Documentation Tools that Do The Hard Work For You

🟢 Bonusmateriaali: Git-työnkulun tarkistuslista versionhallinnan yksinkertaistamiseen & virtaviivaistamiseen

Ilman dokumentointia ohjelmisto on vain musta laatikko. Eivätkä mustat laatikot ole läheskään niin hyödyllisiä kuin ne voisivat olla, koska niiden sisäinen toiminta on piilossa niiltä, jotka tarvitsevat niitä avoimesti.

Ohjelmiston dokumentointi tekee ohjelmistostasi lasisen laatikon selittämällä käyttäjille ja kehittäjille, miten se toimii tai miten sitä käytetään.

Olet luultavasti nähnyt dokumentaatiota ennenkin, mutta jos tarvitset kertausta, tässä on esimerkki Slackin API:sta:

Kuten näet, Slack selittää kaiken sen API:sta piinallisen yksityiskohtaisesti. Kaikki aiheeseen liittyvät sivut on linkitetty, on sivupalkki, jossa on helposti lähestyttäviä aiheita, ja kuvakaappauksia siitä, mitä käyttäjä voi odottaa näkevänsä.

Kerrottuamme tämän tarkemmin käsittelemme tässä Process Street -postauksessa seuraavia aiheita:

• Mitä on ohjelmistodokumentaatio?
• Ohjelmistovaihtoehdot ohjelmistodokumentaatiolle
• Ohjelmistodokumentaation kirjoitustyökalut
• Loppusanat ohjelmistodokumentaatiosta

Aloitetaan.

Mitä on ohjelmistodokumentaatio?

”Ohjelmistotekniikassa dokumentaatio on sateenvarjotermi, joka kattaa kaikki kirjalliset dokumentit ja materiaalit, jotka käsittelevät ohjelmistotuotteen kehitystä ja käyttöä.” – Prototype.io, Software Documentation Types and Best Practices

Kaiken ohjelmiston tulisi sisältää jonkinlaista dokumentaatiota, jossa selitetään yksityiskohtaisesti, mikä tuote on, miten se toimii ja miksi se toimii juuri sillä tavalla.

”Jos sitä ei ole dokumentoitu, sitä ei ole olemassa” – Sitepoint, A Guide to Writing Your First Software Documentation

Kehittäjänä päätavoitteesi on kirjoittaa parasta mahdollista koodia. Haluat, että koodisi on luokkansa parasta, helppolukuista ja helppokäyttöistä, ja haluat, että sen tuloksena tapahtuu hienoja asioita. Eikö niin?

Mutta ilman dokumentointia siitä, mitä olet tehnyt ja miksi olet tehnyt sen:

• Ei kukaan muu voi käyttää koodiasi kuin sinä itse

Ilman dokumentointia kukaan ei ymmärrä, mitä olet tehnyt ja miksi olet tehnyt sen. Jonkun muun on uskomattoman vaikeaa, lähes mahdotonta, ottaa koodisi haltuun ja työskennellä sen parissa. Hän saattaa jopa hylätä sen ja aloittaa alusta, koska joissakin tapauksissa se olisi nopeampaa kuin yrittää selvittää, mitä olet tehnyt ja miksi.

• Et voi päivittää tai parantaa sitä

Pystytkö muistamaan, mitä söit päivälliseksi lauantaina kolme kuukautta sitten? Ellet ole täysin tottunut, et todennäköisesti pysty. On siis reilua sanoa, ettet todennäköisesti muista kirjoittamaasi koodia kahden, kolmen tai neljän kuukauden kuluttua sen tekemisestä. Jos et muista koodauspäätöstesi taustalla olevia syitä, sinun on vaikea pystyä päivittämään tai parantamaan sitä.

Tästä huolimatta ohjelmistodokumentointi on usein tehtävä, jota kiirehditään, tehdään huonosti, vähätellään tai unohdetaan kokonaan.

Ennen kuin alamme puhua siitä, mitä työkaluja voit käyttää ohjelmistodokumentaation kirjoittamiseen, meidän on keksittävä keino varmistaa, että tehtävä ylipäätään tehdään.

Tässä Process Street voi auttaa.

Process Street on BPM-ohjelmisto (Business Process Management), jolla voidaan luoda, hallita ja seurata prosesseja.

Lisää siitä, mikä Process Street on, myöhemmin, nyt näytän sinulle, miten voit käyttää sitä työkaluna, joka auttaa sinua sovittamaan ohjelmistodokumentaation jokaiseen ohjelmistokehitysprojektiin, jossa työskentelet.

Alhaalla on esimerkki valmiista Software Deployment Process -mallista. Tämä malli on luotu auttamaan ohjelmistosuunnittelijoita ja ohjelmoijia ottamaan ohjelmistonsa käyttöön parhaalla mahdollisella tavalla.

Klikkaa tästä päästäksesi ohjelmistojen käyttöönottoprosessiin!

Voidaksesi saada tämän mallin, joko kirjaudu sisään ja lisää se kojelautaasi tai rekisteröidy ilmaiseen kokeilujaksoon.

Tämä malli on täydellinen esimerkki prosessista, jota voit noudattaa aina, kun haluat ottaa käyttöön uuden tai päivitetyn koodin.

Se sisältää selkeät vaiheet, jotka opastavat sinua koko käyttöönottoprosessin läpi aina staging-ympäristön perustamisesta muutosten käyttöönottoon. Nämä vaiheet varmistavat, ettei mitään jää huomaamatta ja että koko prosessi sujuu joka kerta ongelmitta.

Olemme suunnitelleet tämän mallin käytettäväksi oppaana, joka auttaa sinua luomaan juuri sinulle sopivan käyttöönottoprosessin. Jokainen yritys on erilainen, jokainen ohjelmistoprojekti on erilainen ja jokainen käyttöönottoprosessi on erilainen.

Voit muokata tätä prosessia ja lisätä siihen sinulle, yrityksellesi ja projektillesi olennaiset tehtävät.

Tästä pääsenkin takaisin ohjelmistodokumentointiin; voit lisätä tehtäväksi ”ohjelmistodokumentoinnin”. Näin kaikkia, jotka työskentelevät ohjelmiston käyttöönottoprosessin parissa, muistutetaan ja kannustetaan suorittamaan se osana prosessia.

Minulla on muutama muukin valmiiksi tehty prosessimalli, joista voisi olla hyötyä, ja liitän ne tämän viestin loppuun.

Ennen kuin pääsemme tähän, katsotaanpa, missä voit säilyttää ohjelmistodokumentaatiosi.

Ohjelmistodokumentaation isännöintivaihtoehdot

Ei ole hyvä, että tietokoneellasi asuu pelkkä nippu tekstitiedostoja. Kehittäjien ja käyttäjien on päästävä niihin käsiksi, minkä teet mitä todennäköisimmin isännöimällä dokumentteja internetissä, koska kyseessä ei ole 1980-luku.

Process Street (sisäiseen käyttöön)

Jos haluat kouluttaa uusia kehittäjiä ja pitää dokumentaatiosi elävänä kaikki samassa paikassa, Process Street on hyvä valinta ohjelmistodokumentaatiolle.

Voit ensin luoda prosessin dokumentaatiosi kirjoittamista varten, jotta voit varmistaa, että kaappaat kaikki oikeat yksityiskohdat ja teet siitä mahdollisimman hyödyllisen.

Käyttämällä seuraavia helppokäyttöisiä ominaisuuksia voit sitten kirjoittaa ja tallentaa dokumentaatiosi yhteen paikkaan:

• Kuvavidgetit
• Tekstividgetit
• Videovidgetit
• Tiedostovidgetit
• Välilehdet
• Sivutehtävät
• Sähköpostividgetit
• Embed-vidgetit

Dokumentaatiosi tallentaminen Process Streetin sisältä tarkoittaa, että kaikki yrityksessä työskentelevät henkilöt pääsevät käsiksi siihen. Voit jakaa sen muiden kanssa, lähettää sen hyväksyttäväksi, asettaa muistutuksia sen tarkistamisesta ja päivittää sitä helposti.

Katso se:

Jos se voidaan dokumentoida, se voidaan dokumentoida Process Streetissä.

Tilaa ilmainen kokeilujakso täältä ja kokeile sitä.

Read The Docs

On merkittävää, että Read The Docs on ilmainen, kun näkee, mitä kaikkea sillä voi tehdä. GitHubin tapaan voit luoda niin paljon avoimen lähdekoodin materiaalia kuin haluat, joka indeksoidaan avoimesti sivustolle, mutta se maksaa, jos haluat tehdä dokumenteista yksityisiä ja yrityksesi sisäisiä. Meidän tarkoituksiamme varten sinulle todennäköisesti riittää, että dokumentit ovat helposti käyttäjien saatavilla verkossa.

Read The Docs on niin hyvä siksi, että voit vaivattomasti tuoda dokumentaatiota mistä tahansa versionhallintajärjestelmästä, kuten Gitistä, Mercurialista, Subversionista ja Bazaarista. Se tukee myös webhookeja, joten dokumentit rakennetaan automaattisesti aina, kun toimitat koodia.

Katso heidän Getting Started -oppaastaan, jotta saat käsityksen siitä, miten se toimii ja miten dokumenttisi käyttäytyisivät, kun niitä isännöidään siellä.

GitHub (& GitHub-sivut)

Jos käytät GitHubia ohjelmiston versiohallinnan hallintaan, sinulla on ainakin README.MD-tiedosto arkistossa. Jos haluat käyttää GitHubia ohjelmiston dokumentointiin, kuten miljoonat muut ovat tehneet aiemmin, täytä tuo README-tiedosto markdownilla.

Hyvä esimerkki on sferikin t-arkisto, kuvakaappaus täältä:

Jos haluat enemmän kuin yhden arkin muotoiltua tekstiä, voit hyödyntää GitHubin Pages-työkalua (saat yhden ilmaisen verkkosivun + isännöinnin jokaisella GitHub-tilillä, ja voit jopa reitittää siihen oman verkkotunnuksen). Pagesissa on jopa upean näköisiä oletusteemoja, jotka saavat dokumentaatiosi näyttämään ammattimaiselta.

Yllä on atom.io:n dokumentaatio Electronille hostattuna GitHubissa. Se on fiksu valinta, koska se toimii automaattisesti GitHubin versionhallinnan kanssa, aivan kuten muukin ohjelmistosi. Katso sivuston arkisto täältä.

Dropbox Paper (sisäiseen käyttöön)

Sisäiseen ohjelmistodokumentaatiokäyttöön Dropbox Paper on erinomainen valinta. Kuten edeltäjänsä Hackpadin, voit käyttää sitä yksityisen wikin luomiseen työntekijöille. Voit linkittää dokumentteja toisiinsa, lisätä koodilohkoja, kuvia ja sivuhyppyjä, aivan kuten miltä tahansa dokumentointityökalulta voi vaatia.

Kuten oikealla olevista kommenteista näet, voit käyttää sitä myös hyväksyntäprosessien läpikäymiseen ja dokumentaation luomiseen liittyvään yhteistyöhön. Kaiken kaikkiaan se on loistava työkalu dokumentaation sisäiseen kehittämiseen ja luomiseen, kenties tarkoituksena julkaista se myöhemmin tai pitää se vain sisäiseen käyttöön.

Atlassian REST API Browser (API-käyttöön)

Atlassianin REST API Browser (RAB) sisältyy oletusarvoisesti JIRA Server-, Confluence Server- ja Stash-instansseihin. Se on rakennettu JIRA/Confluence-ympäristöissä käytettävissä olevien API:iden löytämiseen, ja se on myös paikka dokumentaation isännöintiin. Jos API-rajapintasi tietysti sopii siihen.

Dokumentoi API-rajapintasi tämän työkalun avulla, jotta JIRA/Confluence-yhteensopiva API-rajapintasi saa enemmän näkyvyyttä. Katso täältä Atlassianin dokumentaatio tämän tekemiseen.

Tettra (sisäiseen käyttöön)

Tettra on eräänlainen tietopohjaohjelmisto, jolla voit dokumentoida kehitystyötäsi tai mitä tahansa.

Käytämme Tettraa sisäisesti Process Streetillä moniin eri käyttötarkoituksiin. Päivittäin käytän Tettraa siihen, että minulla on yksi paikka, jossa kaikki prosessini on dokumentoitu, jotta en koskaan unohda, miten yksi liittyy toiseen tai miten rakentamamme erilaiset automaatiot on asetettu.

Tettra on loistava, jos haluat luoda jonkinlaisen kirjaston. Tämä tarkoittaa, että se sopii loistavasti ohjelmistodokumentointiin tai vaikka vain yrityksesi sisäiseksi wikiksi.

Koska Tettra on suunniteltu nimenomaan tietämyksen hallintaan, siinä on myös paljon muita tukitoimintoja. Se voi esimerkiksi tehdä ehdotuksia siitä, mitä lisäsisältöä tai osioita haluaisit lisätä antaaksesi täydellisemmän kuvan organisaatiostasi ja siitä, miten asiat sopivat yhteen.

Täältä näet pienen videon siitä, miten kehitystiimi voisi käyttää Tettraa: How Product & Engineering Teams Use Tettra.

Od, you can go here to read about how we use Tettra alongside Process Street: Automating Workflows and Checklists: Process Street Case Study.

Check it out!

Apiary (API-käyttöön)

Apiary on paitsi paikka, jossa mehiläiset asuvat, myös API-dokumentaation erityinen isäntä. Kirjoita markdown-kielellä, lisää mock API-kutsuja ja Apiary kokoaa niistä jotain alla olevan kaltaista:

Kuka tahansa voi testata API:ta menemättä sovellukseen tai ohjelmoimatta varsinaista kutsua, mikä tekee siitä erittäin helppokäyttöisen tavan jakaa API:tasi, dokumentoida se perusteellisesti ja ylpeillä sillä, mitä sillä voi tehdä.

Olemme keskustelleet siitä, missä säilytät ohjelmistodokumentaatiosi, ja nyt on aika tarkastella, miten se kirjoitetaan.

Kirjoitustyökalut ohjelmistodokumentaatiota varten

Ohjelmistodokumentaatio kirjoitetaan usein markdown-kielellä, jotta hyperlinkit ja muotoilu ovat mahdollisia, mutta samalla se pysyy pelkkänä tekstinä, jotta se voi elää kooditiedostojen rinnalla versionhallinnassa. Tämä tarkoittaa, että monet valitsemistani kirjoitustyökaluista ovat yksinkertaisia markdown-editoreja, jotka tekevät kirjoittamisesta miellyttävää. Lisäksi joukkoon on heitetty myös pari erittäin tehokasta ei-markdown-ratkaisua.

MarkdownPad (Windows)

MarkdownPad on suosituin markdown-editori Windowsille ilmaisella ja premium-versiolla – molemmissa on paljon hienoja ominaisuuksia. Se on optimoitu blogikirjoituksiin, verkkosivustoihin, artikkeleihin, README-julkaisuihin ja tietenkin ohjelmistodokumentaatioon.

Voit hankkia MarkdownPadin ilmaiseksi tai premium-version 14,95 dollarilla.

iA Writer (Mac)

iA Writer on yksinkertainen, kaunis markdown-editori, jossa on kirjasto-ominaisuus, mikä tarkoittaa, että voit helposti viitata takaisin toisiin dokumentteihin sivupalkissa. Siitä puuttuvat dokumenttien väliset sisäiset linkit, kuten ohjelmistodokumenteissa voisi olettaa olevan, mutta voit aina lisätä ne, kun dokumentti on lopullisessa muodossaan (eli jos se päätyy internetiin sivustolle).

Jos kirjoitat koko dokumentaatiosi yhdelle, hajanaiselle sivulle, voit käyttää sivuhyppyankkureita, jotka auttavat käyttäjiä navigoimaan.

iA Writer maksaa 9,99 dollaria Mac App Storesta.

ProProfs Knowledge Base

Profs Knowledge Base on loistava pieni työkalu dokumenttien luomisen kaikkiin vaiheisiin; kirjoittamisesta ja muokkaamisesta mukauttamiseen, työnkulkujen asettamiseen ja julkaisemiseen. Voit lisätä multimediaa, tuoda olemassa olevaa sisältöä word-dokumenteista, PDF:stä tai PPT:stä, tallentaa asiakirjasta useita versioita ja palauttaa ne tarvittaessa.

Mutta tämän työkalun todellinen kauneus piilee sen käytettävyydessä. Kuka tahansa ja kuka tahansa voi käyttää sitä ohjelmistodokumentaation laatimiseen. Riippumatta siitä, oletko dokumentoinut ohjelmistoja jo vuosia vai vasta äskettäin aloittanut, se on uskomattoman yksinkertainen ja helppokäyttöinen työkalu.

Profsin käyttö on ilmaista, tai voit päivittää premium-pakettiin, joka maksaa 112 dollaria kuukaudessa.

SimpleMDE (selain)

Vaikka voit teknisesti kirjoittaa markdownia millä tahansa tekstinkäsittelyohjelmalla, koska kyseessä on tapa muotoilla pelkkää tekstiä eikä varsinaisesti mikään ”työkalu”, niin ei varmaankaan ole yllättävää, että se onnistuu selaimessasi myös! SimpleMDE on sekä JavaScriptille rakennettu toimiva markdown-editori että avoimen lähdekoodin projekti, josta voit oppia ja jota voit tarvittaessa muokata omaan käyttöösi.

SimpleMDE on 100% ilmainen! Hae lähdekoodi GitHubista täältä.

reStructuredText-editorit

Markdown on yksi kahdesta yleisimmin käytetystä ohjelmiston dokumentaation kirjoittamiseen tarkoitetusta kielestä, mutta on olemassa toinenkin, jota emme ole toistaiseksi tarkastelleet, ja se on reStructuredText. Se on hyvin samankaltainen kuin markdown, mutta se kannattaa opetella ohjelmistodokumentointia varten.

Docutils, reStructuredTextin luoja, on koonnut tänne listan reStructuredText-editoreista, joihin kuuluu mm. seuraavat:

Rekisteröidyn tekstin pointtina on se, että se on helppo konvertoida eri formaattien välillä, erityisesti tavallisesta tekstistä staattiseen verkkosivustoon. Katso lisätietoja täältä.

Työkalut dokumentaation automaattiseen tuottamiseen lähdekoodista

Dokumentaatiossa mikään ei vedä vertoja inhimilliselle kosketukselle (se näkyy selvästi esimerkiksi Slackin ja Giphyn dokumenteissa). Lähtökohtaisesti (varsinkin valtavien lähdekirjastojen kohdalla) on kuitenkin parasta luoda luurankodokumentaatio automaattisesti. Tämä toimii analysoimalla lähdekoodin funktioita ja kommentteja, ja tarjolla on muutamia eri vaihtoehtoja kielestä riippuen:

Ennen kuin luotat pelkästään automaattiseen generointiin, suosittelen lukemaan tämän StackExchange-ketjun, jossa punnitaan hyviä ja huonoja puolia.

Loppusanat ohjelmistodokumentaatiosta

On olemassa paljon hienoja ratkaisuja, pikaratkaisuja ja työkaluja, jotka ovat (rehellisesti sanottuna) lähes identtisiä. Tärkeintä on lopulta se, että

Mikä on tärkeintä, loppujen lopuksi se, että:

a) kirjoitat ohjelmistodokumentaatiota jokaisesta rakentamastasi ohjelmistosta
b) kirjoitat sen kattavasti ja isännöit sitä jossakin paikassa, johon käyttäjä pääsee käsiksi

Mainitsin aiemmin, että minulla on vielä muutama kehitysprosessin malli, joita voisit ehkä haluta tutustua?

Noh, tässä ne ovat…

Process Street -kehitysprosessimallit

Ennen kuin annan sinulle nämä mallit, selitän hieman lisää, mikä Process Street on.

Tiedämme siis, että Process Street on supertehokkaita tarkistuslistoja. Se on ohjelmisto, joka auttaa sinua luomaan ja hallitsemaan prosesseja.

Mutta odota, Process Streetissä on muutakin!

Katso tämä esittelyvideo nähdäksesi, mitä tarkoitan:

Näet siis, että voit paitsi luoda kehitysprosessin mallin ja suorittaa siitä yksittäisiä tarkistuslistoja aina, kun sinun on saatettava kehitysprosessi päätökseen, vaan voit myös muokata sitä näiden lisäominaisuuksien avulla

• Tehtävien pysäyttäminen
• Dynaamiset eräpäivät
• Tehtävien käyttöoikeudet
• Ehdollinen logiikka
• Hyväksyntätehtävät
• Embedwidget
• Roolinjako

Tehtävien jakaminen, saat hyväksynnän, määrität järjestyksen, jossa tehtävät suoritetaan, ja voit liittää prosessin tuhansiin sovelluksiin Zapierin, webhookien tai API-integraation avulla.

Katso tämä webinaari uusimmista ominaisuuksistamme ja katso, miten saat niistä kaiken irti:

Tämä kaikki mielessäsi, tutustu alla oleviin valmiisiin malleihin:

Verkon tietoturva-auditoinnin tarkistuslista

Tätä mallia voi käyttää riskienhallintapäällikkö tai vastaava IT-ammattilainen arvioimaan verkon tietoturva-aukkojen varalta.

Klikkaa tästä päästäksesi käsiksi verkon tietoturva-auditoinnin tarkistuslistaan!

Kuukausittainen verkkosivuston ylläpidon tarkistuslista

Käytä tätä kuukausittaisen verkkosivuston ylläpidon tarkistuslistaa optimoidaksesi sivustosi latausnopeutta, skannataksesi haavoittuvuuksia ja tarkastellaksesi hakunäkyvyyttäsi.

Klikkaa tästä päästäksesi käsiksi kuukausittaisen verkkosivuston ylläpidon tarkistuslistaan!

Ohjelmiston testauksen opetusohjelma

Tämän prosessin avulla voidaan hallinnoida kokonaista ohjelmistonkehittämisprojektiä alusta loppuun, mukaan lukien suunnittelu, asiakaskäsittely sekä myös lanseerauksenjälkeiset tarkistukset.

Klikkaa tästä päästäksesi ohjelmistotestauksen opetusohjelmaan!

Ja siinä se on.

Olet nyt vapaa käyttämään sitä, mikä helpottaa elämääsi. Toivottavasti löydät uuden suosikkityökalusi tästä listasta.