; ; ~ftp/staff-docs/Dokumentointi -- Hakemistojen dokumentointi ; ; Status: Draft ; Author: ojala@funet.fi ; Created: Tue May 28 13:12:25 1991 ; Last modified: Tue May 28 15:55:29 1991 ; Petri Ojala FUNET Dokumentointi 1. Dokumentointitarpeet Nic.funet.fi:n kaltaisissa isoissa ohjelma-arkistoissa k{yt{nn|n ongelmista suurin on yleens{ aina dokumentointi. Eri aihepiireill{ on useimmiten eri yll{pit{j{t, jolloin dokumentoinnin yhten{ist{minen tuottaa ongelmia ja toisaalta eri yll{pit{jill{ on erilainen m{{r{ resursseja k{ytett{viss{{n arkistonsa yll{pitoon. Toisaalta ongelmana on my|s tiedon suuri m{{r{ - Funicin MS-DOS alueella on t{ll{ hetkell{ n. 8500 tiedostoa, joiden t{ydellinen dokumentointi edellytt{isi todenn{k|isesti v{hint{{n ty|vuoden ty|n. Toisaalta jos tiedostot dokumentoidaan lyhyesti k{y helposti siten, ett{ dokumentointi ei v{ltt{m{tt{ anna riitt{v{n selke{{ kuvaa ohjelmistosta ja potentiaalinen ohjelman tarvitsija ei ohjelmaa l|yd{. Dokumentointarpeet voidaan jakaa l{hinn{ kahteen p{{luokkaan: yll{pit{jien tarpeet ja k{ytt{jien tarpeet. Yll{pit{jille ei niink{{n ole tarpeellista ohjelman toiminnan kuvaus, vaan esimerkiksi tiedoston formaatti, mist{ tiedosto on alunperin haettu ja kuka sen on hakenut. K{ytt{j{n kannalta taas edell{mainitut tiedot ovat toissijaisia ja tarpeiden painopiste on enemm{nkin siin{, mit{ ohjelma tekee ja mink{laiseen k{ytt||n se on tarkoitettu. 2. Miten Funicin dokumentointi tulisi hoitaa - ideoita Itse n{kisin parhaimpana ratkaisuna ty|m{{r{n ja k{ytt|kelpoisuuden kompromissin, jossa paikallisesti tiedostot pyrit{{n dokumentoimaan kohtuullisen lyhyesti, eli helposti ja vaivatta tuotetuilla dokumenteill{ ja toisaalta tarkempi dokumentoi pyrit{{n aikaansaamaan automaattisesti esimerkiksi README-tiedostoista ja toisaalta verkossa jo olemassa materiaalista (esimerkiksi comp.archives uutisryhm{). Ep{ilen ett{ perinteiset tietokanta-ajatukset ovat k{ytt{j{n kannalta k|mpel|it{ ja toisaalta my|s vaivalloisia k{ytt{{, mik{li k{ytt{j{ ei tarkalleen tied{ mit{ haluaa - kuten yleens{ tilanne on, jos jotain tuntematonta ohjelmistoa etsit{{n. Vaihtoehtona perinteiselle tietokannalle on l{hinn{ vapaamuotoinen tekstinhaku. Tietokantoja pit{isi olla useita, joista haku tapahtuu "puumaisesti" gxxxx, 00Readme jne. tyyliset tiedostot) Kukin tietokanta generoidaan eri hakemistoista siten, ett{ esimerkiksi jokaisella public-alueella on oma tietokantansa ja suuren public-alueen ollessa kyseess{ tietokantoja voi olla jopa jokaista alihakemistoa varten erikseen. Syit{ moniin tietokantoihin on haun kohdistamisen lis{ksi my|s se, ett{ tietokanta on helpompi p{ivitt{{ jos lis{tt{v{{ tietoa ei ole liikaa. K{ytt{jille suunnattujen tietokantojen lis{ksi olisi erikseen l{hinn{ yll{pit{jille ja ohjelmille tarkoitetut tiedostot, jotka olisivat l{hinn{ koneluettavassa muodossa erillisiss{ tiedostoissa. 3. Yll{pidollinen dokumentointi 3.1. Yll{pitotoimien dokumentointi Erilaiset yll{pit{jille tarkoitetut dokumentit on koottu hakemistoon ~ftp/staff-docs (/ftp/staff-docs) ja ne ovat ensisijaisesti suomeksi mutta usein my|s englanniksi. Ensisijainen kohderyhm{ ko. dokumenteille ovat eri public-alueiden yll{pit{j{t sek{ my|s erityisen kiinnostuneet k{ytt{j{t. Tavalliselle perusk{ytt{j{lle niist{ ei v{ltt{m{tt{ ole hy|ty{. Tarpeiden mukaan dokumentit on sijoitettu alihakemistoihin aihepiirien mukaisesti. 3.2. Ohjelmalliset dokumentit Ohjelmallisella dokumentoinnilla tarkoitetaan ensisijaisesti tiedostoja, joiden tarkoituksena on dokumentoida ohjelmille public-aluetta. K{yt{nn|ss{ t{m{ tarkoittaa sit{, ett{ tiedostosta on esimerkiksi ymp{rist|muuttujien avulla saatavailla tietoa tai muutoin helposti ohjelmallisesti k{sitelt{v{{ tietoa. Koneluettavien tiedostojen nimi tulisi alkaa '.db' tekstill{. Suositeltava nimi yleistiedoille public-alueesta tai -hakemistosta olisi '.dbinfo'. Itse tiedosto koostuu kommenteista ja muuttuja-asetuksista. Kommentit ovat rivej{ jotka alkavat '#' merkill{. Muuttujien m{{ritykset ovat muodossa nimi=arvo esimerkiksi db_format=lharc Tiedoston kokoa ei ole erityisesti rajattu. Kokonaisuudessaan tiedoston tulisi olla selke{ kompromissi tarpeellisen tiedon ja riitt{v{n dokumentoinnin osalta. Kommentointia siis kannattaa k{ytt{{. Tiedoston pit{{ olla my|s automaattisesti generoitavissa ohjelmallisesti sek{ tietoja pit{{ pysty{ automaattisesti p{ivitt{m{{n. 3.2.1. M{{ritellyt muuttujat db_readme Kertoo tiedoston nimen (suhteellinen polku), josta paikallinen 'Read me first' tiedosto l|ytyy (Ks. suositus alla). db_index Kertoo tiedoston nimen (suhteellinen polku), josta paikallinen Index-tiedosto l|ytyy (Ks. suositus alla). db_format Arkistointitapa 3.2.2. Muuttujien arvot Jotta samalle asialle ei olisi useita eri merkint{tapoja, tulisi samasta asiasta puhuttaessa k{ytt{{ seuraavia "standardoituja" esitystapoja: Tiedoston pakkaustavat: lharc LHARC arc ARC pkzip ZIP tar.Z Compressed tar tar Tar 4. K{ytt{jille tarkoitettu dokumentointi 4.1. Read me first, Lue minut -tiedosto T{m{n tiedoston tarkoitus on toimia k{ytt{j{lle ensimm{isen{ tiedonl{hteen{. Sis{ll|lt{{n sen pit{{ olla riitt{v{n kattava mutta toisaalta my|s riitt{v{n selke{, jotta se soveltuu sek{ aloittelijoille ett{ edistyineille k{ytt{jille. Tiedoston nimi tulisi olla '00Reame' ja/tai '00Lue.minut' riippuen siit{ mill{ kielell{ se on kirjoitettu. 00Readme tiedosto tulee l|yty{ jokaiselta /pub tason hakemistolta sek{ mielell{{n my|s muistakin hakemistoista (voi olla t{ll|in vain yksinkertaisesti kova linkki samaan tiedostoon). Tiedostosta tulisi ilmet{ mm. seuraavat asiat: - Mist{ arkistosta on kyse (nic.funet.fi) - Miten alueen yll{pit{j{t tavoittaa (E-mail -osoite alueen yll{pidolle. Osoitteen tulisi ehdottomasti olla 'anonyymi' mail-alias jotta alueen yll{pitomuutokset eiv{t haittaa k{ytt{ji{. Esimerkiksi unix@nic.funet.fi yksitt{isen k{ytt{j{n sijaan) - Lista henkil|ist{, jotka aluetta pit{v{t yll{ E-mail osoitteineen - Kuvaus hakemistorakenteesta kyseisell{ tasolla - Kuvaus tiedostojen formaatista - Tieto siit{ mist{ tarvittavat purkuohjelmistot on saatavilla ja miten niit{ k{ytet{{n Tekstin tulisi olla tyylilt{{n vapaata. 4.2. Index-tiedosto