Hyvä ohjelmistoasiakirja, olipa kyseessä sitten ohjelmoijien ja testaajien tekniset asiakirjat, tekniset asiakirjat sisäisille käyttäjille tai käyttöoppaat ja ohjetiedostot loppukäyttäjille, auttaa käyttäjiä ymmärtämään ohjelmiston ominaisuudet ja toiminnot. Hyvä dokumentaatio on dokumentaatiota, joka on täsmällinen, selkeä ja olennainen, ja sisältää kaikki käyttäjän tarvitsemat tiedot. Tämä artikkeli opastaa sinua kirjoittamaan ohjelmistoasiakirjoja teknisille käyttäjille ja loppukäyttäjille.
Vaihe
Tapa 1 /2: Ohjelmistoasiakirjojen kirjoittaminen teknisille käyttäjille
Vaihe 1. Tiedä mitä tietoja sisällyttää
Erittelyasiakirjaa käytetään käyttöoppaana käyttöliittymäsuunnittelijoille, ohjelmoijille, jotka kirjoittavat koodia, ja testaajille, jotka tarkistavat ohjelmiston suorituskyvyn. Sisällytettävät tiedot riippuvat luotavasta ohjelmasta, mutta ne voivat sisältää seuraavaa:
- Sovelluksen tärkeät tiedostot, kuten kehitystiimin luomat tiedostot, tietokannat, joita käytetään ohjelman ollessa käynnissä, ja kolmannen osapuolen sovellukset.
- Toiminnot ja aliohjelmat, mukaan lukien selitys toiminnon/aliohjelman käytöstä, tulo- ja lähtöarvot.
- Ohjelmamuuttujat ja -vakiot ja niiden käyttö.
- Ohjelman kokonaisrakenne. Asemapohjaisissa ohjelmissa sinun on ehkä kuvattava jokainen moduuli ja kirjasto. Tai jos kirjoitat käsikirjaa verkkopohjaiselle ohjelmalle, sinun on ehkä selitettävä, mitä tiedostoja kukin sivu käyttää.
Vaihe 2. Päätä, minkä tason dokumentaation pitäisi olla läsnä ja erotettavissa ohjelmakoodista
Mitä teknisempi dokumentaatio sisältyy ohjelmakoodiin, sitä helpompi on päivittää ja ylläpitää sitä sekä selittää ohjelman eri versiot. Ohjelmakoodin dokumentaation tulee sisältää vähintään funktioiden, aliohjelmien, muuttujien ja vakioiden käyttö.
- Jos lähdekoodisi on pitkä, voit kirjoittaa dokumentaation ohjetiedostoon, joka voidaan sitten indeksoida tai hakea tietyillä avainsanoilla. Erilliset dokumentaatiotiedostot ovat hyödyllisiä, jos ohjelmalogiikka on jaettu useille sivuille ja se sisältää tukitiedostoja, kuten verkkosovelluksen.
- Joillakin ohjelmointikielillä (kuten Java, Visual Basic. NET tai C#) on omat koodidokumentaatiostandardinsa. Noudata tällöin vakiodokumentaatiota, joka on sisällytettävä lähdekoodiin.
Vaihe 3. Valitse sopiva dokumentointityökalu
Joissakin tapauksissa dokumentointityökalu määräytyy käytetyn ohjelmointikielen mukaan. Kielillä C ++, C#, Visual Basic, Java, PHP ja muilla on omat dokumentointityökalunsa. Jos ei, käytetyt työkalut riippuvat kuitenkin vaadituista asiakirjoista.
- Tekstinkäsittelyohjelma, kuten Microsoft Word, sopii asiakirjojen tekstitiedostojen luomiseen, kunhan dokumentaatio on tiivis ja yksinkertainen. Luodakseen pitkiä asiakirjoja monimutkaisella tekstillä useimmat tekniset kirjoittajat valitsevat erikoistuneen dokumentointityökalun, kuten Adobe FrameMakerin.
- Ohjetiedostot lähdekoodin dokumentoimiseksi voidaan luoda tukitiedostojen luontiohjelmalla, kuten RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare tai HelpLogix.
Tapa 2/2: Ohjelmistoasiakirjojen kirjoittaminen loppukäyttäjille
Vaihe 1. Tiedä käsikirjan luomiseen liittyvät liiketoiminnan syyt
Ohjelmistoasiakirjojen pääasiallinen syy on auttaa käyttäjiä ymmärtämään sovelluksen käyttöä, mutta asiakirjojen luomisen taustalla voi olla useita muita syitä, kuten markkinointiosaston auttaminen sovelluksen myymisessä, yrityksen imagon parantaminen ja teknisen tuen vähentäminen. kustannuksia. Joissakin tapauksissa asiakirjat vaaditaan säännösten tai muiden lakisääteisten vaatimusten noudattamiseksi.
Dokumentaatio ei kuitenkaan korvaa käyttöliittymää. Jos sovelluksen toiminta vaatii paljon asiakirjoja, se on suunniteltava intuitiivisemmaksi
Vaihe 2. Tunne dokumentaation kohdeyleisö
Ohjelmistokäyttäjillä on yleensä vain vähän tietotekniikkaa niiden käyttämien sovellusten lisäksi. Dokumentaatiotarpeet voidaan tyydyttää useilla tavoilla:
- Kiinnitä huomiota ohjelmiston käyttäjän otsikkoon. Esimerkiksi järjestelmänvalvoja ymmärtää yleensä erilaisia tietokoneohjelmia, kun taas sihteeri tietää vain sovellukset, joita hän käyttää tietojen syöttämiseen.
- Kiinnitä huomiota ohjelmiston käyttäjiin. Vaikka heidän tehtävänsä ovat yleensä yhteensopivia suoritettavien tehtävien kanssa, näillä tehtävillä voi olla eri työtaakkoja toimipaikasta riippuen. Haastattelemalla potentiaalisia käyttäjiä voit selvittää, onko arviosi heidän työnimestään oikea.
- Kiinnitä huomiota olemassa olevaan dokumentaatioon. Ohjelmistotoimintojen dokumentaatiossa ja teknisissä tiedoissa voidaan näyttää, mitä käyttäjien on tiedettävä voidakseen käyttää niitä. Muista kuitenkin, että käyttäjät eivät ehkä ole kiinnostuneita tietämään ohjelman "sisäpiiristä".
- Tiedä mitä tarvitaan tehtävän suorittamiseen ja mitä se vaatii ennen kuin voit suorittaa sen.
Vaihe 3. Määritä asiakirjoille sopiva muoto
Ohjelmistodokumentaatio voidaan järjestää 1 tai 2 muodossa, nimittäin viitekirjoja ja käsikirjoja. Joskus näiden kahden muodon yhdistäminen on hyvä ratkaisu.
- Viitemuotoja käytetään kuvaamaan kaikkia ohjelmiston ominaisuuksia, kuten painikkeita, välilehtiä, kenttiä ja valintaikkunoita ja niiden toimintaa. Jotkut ohjetiedostot on kirjoitettu tässä muodossa, erityisesti ne, jotka ovat asiayhteydelle herkkiä. Kun käyttäjä napsauttaa Ohje tietyssä näytössä, käyttäjä saa aiheeseen liittyvän aiheen.
- Manuaalista muotoa käytetään selittämään, miten tehdä jotain ohjelmistolla. Käsikirjat ovat yleensä tulostettuja tai PDF -muodossa, vaikka joillakin ohjesivuilla on myös ohjeita tiettyjen asioiden tekemisestä. (Yleensä manuaaliset muodot eivät ole asiayhteysherkkiä, mutta ne voidaan linkittää asiayhteyteen liittyvistä aiheista). Käsikirjat ovat yleensä oppaan muodossa, jossa on yhteenveto suoritettavista tehtävistä kuvauksessa ja opas on muotoiltu vaiheittain.
Vaihe 4. Päätä asiakirjatyypistä
Ohjelmistoasiakirjat käyttäjille voidaan pakata yhteen tai useampaan seuraavista muodoista: painetut oppaat, PDF -tiedostot, ohjetiedostot tai online -ohjeet. Jokainen dokumentaatiotyyppi on suunniteltu näyttämään sinulle, kuinka ohjelmiston toimintoja käytetään, olipa kyseessä sitten opas tai opetusohjelma. Online -dokumentaatio ja ohjesivut voivat sisältää myös esittelyvideoita, tekstiä ja staattisia kuvia.
Online -ohje- ja tukitiedostot on indeksoitava ja haettavissa avainsanoilla, jotta käyttäjät voivat löytää tarvitsemansa tiedot nopeasti. Vaikka ohjetiedostogeneraattorisovellus voi luoda hakemiston automaattisesti, on silti suositeltavaa luoda hakemisto manuaalisesti käyttämällä yleisesti haettuja avainsanoja
Vaihe 5. Valitse sopiva dokumentointityökalu
Tulostettuja käyttöoppaita tai PDF -tiedostoja voidaan luoda tekstinkäsittelyohjelmalla, kuten Word, tai kehittyneellä tekstieditorilla, kuten FrameMaker, tiedoston pituudesta ja monimutkaisuudesta riippuen. Ohjetiedostot voidaan kirjoittaa ohjetiedostojen luontiohjelmalla, kuten RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix tai HelpServer.
Vinkkejä
- Ohjelma -asiakirjan tekstin tulee olla rakenteeltaan sellainen, että se on helppo lukea. Aseta kuva mahdollisimman lähelle sopivaa tekstiä. Jaa asiakirjat loogisesti osioiden ja aiheiden mukaan. Jokaisen osion tai aiheen tulisi kuvata tietty ongelma, sekä tehtävät että ohjelman ominaisuudet. Aiheeseen liittyvät ongelmat voidaan selittää linkkien tai viitelistojen avulla.
- Jokaista tässä artikkelissa kuvattua dokumentaatiotyökalua voidaan täydentää kuvakaappausohjelmalla, kuten SnagIt, jos dokumentaatiosi vaatii useita kuvakaappauksia. Kuten kaikki muutkin asiakirjat, sinun tulee myös sisällyttää kuvakaappauksia, jotka auttavat selittämään, miten sovellus toimii, eikä "houkutella" käyttäjää.
- Tyyliin kiinnittäminen on erittäin tärkeää, varsinkin jos kirjoitat ohjelmistoasiakirjoja loppukäyttäjille. Osoita käyttäjiä pronominilla "sinä" käyttäjän "sijaan".
