Ohjelmointirajapintojen käyttäjien tietotarpeiden tukeminen dokumentaation avulla

Abstract

Ohjelmointirajapinnat (engl. Application Programming Interface, API) sekä niiden rajapintadokumentaatio ovat keskeinen osa modernia ohjelmistokehitykstä. Tämä kandidaatintyö kartoittaa ohjelmoijien tietotarpeita heidän opetellessaan käyttämään uusia rajapintoja sekä tapoja tukea ohjelmoijia rajapintadokumentaation avulla.

Ensin käsitellään ohjelmoijien tietotarpeita heidän käyttäessään uusia rajapintoja. Rajapintoja opetellessa ohjelmoijilla on kärjistetysti kaksi tavoitetta: selvittää, onko rajapinnalla mahdollista ratkaista jokin ongelma sekä oppia käyttämään rajapintaa ongelman ratkaistakseen. Ensiksi uuteen rajapintaan tutustuessa ohjelmoijat pyrkivät saamaan rajapinnan tarkoituksesta ja toiminnoista korkeamman tason käsityksen. Korkeamman tason käsityksen saatuaan ohjemoijat jakautuvat karkeasti kahteen ryhmään oppimisstrategian mukaan: toiset ohjelmoijat ovat koodiorientoituneempia ja pyrkivät rajapinnan nopeaan käyttöönottoon sekä ongelmansa ratkaisuun, ja toiset ovat käsiteorientoituneempia ja pyrkivät oppimaan rajapintaa syvemmin ja järjestelmällisemmin.

Lopuksi perehdytään rajapintadokumentaation rakenteeseen ja sisältöön. Rakenteen puolesta ohjelmoijille erityisen tärkeää on selkeää jäsentely ja tiedon löydettävyys. Toisteisuutta ja itsestäänselvää tietoa kannattaa välttää, ja hajauttamisen sijaan kannattaa suosia tiedon paikallisuutta. Sisällön suhteen tärkeää on huomioida dokumentaation ajantasaisuus, valmius ja kattavuus. Dokumentaation on hyvä tukea nopean yleiskatsauksen saamista, ja sisällössä kannattaa huomioida oikeantasoinen läpäisevyys eli analysoinnin ja ymmärtämisen tukeminen ilman liikainformaatiota. Rajapinnan suunnitteluun liittyviä tarkoituksia ja päätöksiä voi dokumentoida tarvittaessa. Erityisen tärkeä osa rajapintadokumentaation sisältöä ovat informaatiopitoiset koodiesimerkit, jotka toimivat ohjelmoijille ensikosketuksena rajapintaan ja opettavat sen oikeaoppista käyttöä. Koodiesimerkkien laatu ja oikeantasoinen opettavuus on tärkeä varmistaa.