Ideologisesti sopivan teknisen dokumentaation tekeminen ohjelmistoille tuntuu luonnolliselta suhteelta. Dokumentaation tulisi virrata yhtä vapaasti kuin ohjelmien itsensä, tehden estottomia muuttoliikkeitä medioiden välillä, kenen tahansa sitä tahtovan ruutuihin ja kirjahyllyihin. Kenen tahansa pitäisi voida uudelleenjakaa, muuttaa, myydä tai antaa teknistä dokumentaatiota ilmaiseksi kenelle tahansa. Jos tekniselle dokumentaatiolle ei voi tehdä näin, se ei ole vapaata.
On sääli, että Free Software Foundationin Free Documentation License ("Vapaa dokumentaatiolisenssi") sitoo sisällön joukkoon erilaisia joustamattomia vaatimuksia, jotka haittaavat tätä vapautta. Debian Foundation on kritisoinut lisenssiä ja todennut:
"Ei ole mahdollista lainata tekstiä GFDL-lisenssin alaisesta käyttöoppaasta ja liittää sitä mihinkään vapaaseen ohjelmaan. Tämä ei ole pelkkää lisenssien yhteensopimattomuutta. Ongelma ei ole pelkästään GFDL:n yhteensopimattomuus tämän tai tuon vapaan ohjelmalisenssin kanssa: kyseessä on se, että se on pohjimmiltaan yhteensopimaton minkä tahansa ohjelmistolisenssin kanssa. Jos kirjoitat uuden ohjelman ja sinulla ei ole mitään sitoumuksia lisenssin käytön suhteen, paitsi että sen täytyy olla vapaa lisenssi, et voi liittää siihen GFDL-tekstiä.
GNU FDL on nykyisessä muodossaan yhteensopimaton Debian Free Software Guidelinesin kanssa. Tämän lisenssin kanssa on merkittäviä ongelmia, [...] ja emme sellaisenaan voi hyväksyä GNU FDL:n alaisia töitä ohjelmistojakeluumme."
http://people.debian.org/~srivasta/Position_Statement.xhtml
Kenties tämän lisenssin perusajatus - dokumentaatio liitetään käyttöoppaaseen, käyttöopas liittäminen kirjaan, kirja liitetään julkaisijaan, julkaisija liitetään yhtiöön - on asettanut Free Software Foundationin kurssille, joka haittaa sen mainetta vapauden puolustajina.
Erityisesti:
Nämä ongelmat johtuvat lisenssin perusajatuksesta. On kaksi eri oletusta, jotka johtavat ongelmallisiin vaatimuksiin:
1. FDL näyttää ajattelevan, että tekninen kirjoittaminen sisältää vapaiden ohjelmistojen poliittisia palopuheita. Viittaan tähän lausuntoon:
"Käyttöoppaamme sisältävät osia, jotka esittävät poliittisen näkemyksemme vapaista ohjelmistoista. Merkitsemme nämä 'muuttumattomiksi', joten niitä ei voi poistaa tai muuttaa. GFDL asettaa vaatimuksia näiden 'muuttumattomien osien' suhteen.
http://www.gnu.org/licenses/gpl-faq.html#WhyNotGPLForManuals
Hyvä tekninen kirjoittaja ei sepitä poliittisia mielipidekirjoituksia.
2. FDL olettaa teknisen kirjoittamisen olevan kustannustoimintaa. Viitteenä:
"GFDL sisältää klausuuleja, jotka auttavat vapaiden käyttöoppaiden julkaisijoita tekemään voittoa kappaleiden myynnistä"
http://www.gnu.org/licenses/gpl-faq.html#WhyNotGPLForManuals
"Vapaat lisenssit" eivät saisi estää niiden alaisena olevien asioiden kaupallista käyttöä. Tämä on vapauden periaate - voit käyttää ohjelmia tai dokumentaatiota miten haluat, kunhan säilytät muilla samat vapaudet. Kuitenkin huomion kohteena pitäisi olla vapauden eikä tiettyjen liiketaloudellisten mallien säilyttäminen. Voitko kuvitella samanlaista klausuulia GPL:ssä? Sitä haukkuisi vapauden rajoittamisesta sekä Richard Stallman että FSF ja sen käyttö lopetettaisiin heti. Sääli, että Richard Stallman ja FSF eivät käytä samanlaisia vapauskäsitteitä vapaiden ohjelmistojen koulutuksessa. Jos he tekisivät niin, tämä ja muita ongelmia ratkaistaisiin nopeasti.
Yllä on mainittu vain tärkeimmät huolenaiheet FDL-lisenssin ajatusmaailman suhteen. Näillä kahdella ongelmalla on sekä ideologisia että käytännöllisiä seurauksia, joiden vuoksi on hyvin vaikeaa käyttää FDL-lisenssiä, jos tahdot kirjoittaa vapaata dokumentaatiota vapaille ohjelmille.
Ideologiset ongelmat ovat selviä - mutta tämä järkeily tekee myös lisenssistä käytännössä käyttökelvottoman. Esimerkiksi on olemassa jatkuvia viittauksia kirjan elementteihin, kuten "otsikkosivut", "kannet" jne. Eräs tietty klausuuli, jota on vaikea seurata, on tämä osa, joka vaatii, että työn muokatun version täytyy:
"A. Käyttää otsikkosivulla (ja kansissa, jos niitä on) erilaista otsikkoa kuin dokumentissa, ja erilaista kuin edellisissä versioissa (jotka tulisi, jos edellisiä versioita on, listata dokumentin historia-osassa). Voit käyttää samaa otsikkoa kuin edellisissä versioissa, jos kyseisen version alkuperäinen julkaisija antaa lupansa."
Tässä lausunnossa on niin monta ongelmaa, että on vaikea tietää mistä aloittaa. Mikä on esimerkiksi "historian" rooli dokumentissa, joka voi olla yhden "sivun" pituinen? Entä muutaman lauseen pituinen dokumentaatio? Pääongelma tässä klausuulissa on kuitenkin, että digitaalisen dokumentaation pitäisi virrata kuin vesi yhdeltä tekniseltä kirjoittajalta toiselle, jotta on mahdollisimman paljon joustavuutta lisätä, poistaa ja remiksata dokumentaatiota. On hankalaa, jos vaaditaan "siirtymistä taaksepäin" alkuperäiseen tekniseen kirjoittajaan, jotta samaa otsikkoa voidaan käyttää. Tämä haittaa materiaalin uudelleenkäyttöä ja on logistisesti vaikeasti ylläpidettävissä tänä vapaasti liikkuvan dokumenttien jakelun aikakautena.
Tässä on toinen kirjoihin liittyvä ongelma, joka rajoittaa vapautta:
"Jos julkaiset dokumentista painettuja kopioita (tai kopioita medioissa, joilla on yleensä painetut kannet), kopioita on yli 100, ja dokumentin lisenssiteksti vaatii kansitekstejä, kopiot täytyy sulkea kansiin, joissa on, selkeästi ja erottuvasti, kaikki nämä kansitekstit: etukannen tekstit etukannessa, takakannen tekstit takakannessa. Molempien kansien täytyy selkeästi ja luettavasti identifioida sinut näiden kopioiden julkaisijana. Etukannessa täytyy lukea koko otsikko niin, että kaikki otsikon sanat ovat yhtä selkeästi näkyvillä. Voit lisätä muuta materiaalia kansiin. Kopiointia kansiin rajoittuvilla muutoksilla, niin kauan kuin ne säilyttävät dokumentin otsikon ja tyydyttävät nämä vaatimukset, voidaan käsitellä sananmukaisena kopiointina muissa suhteissa."
Miksi vapaan dokumentaation teknisen kirjoittajan pitäisi välittää siitä, kuinka monta dokumenttia painat? Itse tahdon materiaalin olevan mahdollisimman laajassa käytössä. Ole hyvä, printtaa niin monta kuin tahdot, miten tahdot, missä tahansa muodossa tahdot. Vapaan dokumentaation tekniset kirjoittajat eivät tahdo sekaantua monimutkaisiin klausuuleihin, joihin kuuluu "kansitekstit", "etukannen tekstit" ja satunnaiset numeromäärien rajoitukset, jotka rajoittavat vapauttasi käyttää dokumentaatiota kuten tahdot. He tahtovat materiaalin olevan mahdollisimman laajassa käytössä.
Tarvitsemme dokumentaatiolle samoja vapauden periaatteita kuin koodille, ja Free Documentation License (FDL) ei säilytä mainittuja vapauden periaatteita. Tämän kirjoittamisen ajankohtana tätä lisenssiä laaditaan uudelleen ja näyttää siltä, kuin se jaettaisiin kahteen lisenssiin. Kuitenkaan kumpikaan näistä uudelleenkirjoitetuista versioista ei koske näihin perusongelmiin. Tarvitsemme lisenssin, joka menee pidemmälle kuin FDL, ja joka sallii käyttäjien tekevän dokumentaatiolla mitä voivat tehdä lähdekoodin kanssa. Onneksi on lisenssi joka sallii tämän - General Public License (GPL). Tämän lisenssin alla useimmat vapaat ohjelmat ja avoimen lähdekoodin projektit julkaisevat lähdekoodinsa. GPL:n hyvin tunnetun historian ja perinteen vuoksi monet uskovat sen soveltuvan vain ohjelmistoihin, kuitenkin lisenssi sopii mihin tahansa sisältöön, kuten FSF itsekin myöntää:
"mikä tahansa minkä tahansa tyyppinen työ voidaan asettaa GNU GPL -tekijänoikeuden alaiseksi."
http://www.gnu.org/philosophy/nonsoftware-copyleft.html
Vapaiden ohjelmien dokumentoinnin pitäisi jakaa samat vapauden periaatteet kuin itse ohjelman. Pitäisi näin ollen voida käyttää GPL-lisenssiä, kun projektin koodikin käyttää GPL:ää. Jos et usko tähän ideologiseen argumenttiin, voit kysyä itseltäsi kaksi yksinkertaista käytännöllistä kysymystä. Pitäisikö ohjelmoijien voida käyttää vapaan dokumentaation teknisten kirjoittajien työtä liittämällä dokumentaatio ohjelmaan? Pitäisikö olla mahdollista jakaa vapaata dokumentaatiota sen ohjelman kanssa, jota on dokumentoitu?
Jos vastauksesi on "kyllä" edes toiseen näistä kysymyksistä, sinulla ei ole paljonkaan vaihtoehtoja lisenssien suhteen. Lisenssien yhteensopivuus sisältää monia monimutkaisia ongelmia, joita harvat Software Freedom Law Centerin ulkopuolella näyttävät ymmärtävän. Monet - esimerkiksi Debian-projekti - väittävät vakuuttavasti, että Free Documentation License ei ehkä ole yhteensopiva GPL:n kanssa. On kuitenkin yksi lisenssi joka mahdollistaa dokumentaation helpon jakamisen GPL-ohjelmien kanssa - se on GPL-lisenssi. Ainoa syy vaivautua käyttämään toista lisenssiä on, että vapaiden ohjelmistojen projekti, jota dokumentoit, käyttää toista lisenssiä kuin GPL. Tässä tapauksessa kannattaa antaa dokumentaatiolle sama lisenssi kuin koodille.
Pikemminkin käytännöllisestä kuin ideologisesta näkökulmasta tarkasteltuna vapaa dokumentaatio on parempaa kuin suljettu dokumentaatio. Muuntelun helppous on voimavara, jonka kanssa suljettu dokumentaatio ei voi kilpailla. Vapaata dokumentaatiota voi päivittää samaan aikaan kuin ohjelmaa päivitetään ja parannetaan monelle taholle jaetun ongelmanratkaisun avulla ("monta silmää tekee kaikista ohjelmointivirheistä pinnallisia"), se voidaan kääntää omalle kielellesi, tai muokata uutta ympäristöä varten sopimaan paremmin henkilökohtaisiin tai organisaation tarpeisiin. Vapaa tekninen dokumentaatio on näistä näkökulmista parempi idea kuin suljettu dokumentaatio, ja voi hyvin toteutettuna edistää valtavasti vapaiden ohjelmistojen käyttöä.
Nyt tahtoisin puhua hieman joistain ominaisuuksista, joita hyvällä vapaalla dokumentaatiolla tulisi olla:
On järkevää, että jos jotain voidaan parannella, sitä voidaan myös parannella helposti. Monet vapaan dokumentaation projektit ottavat teknologisen strategiansa vapaiden ohjelmistojen kehitymenetelmistä. Nämä projektit tallentavat sisältönsä CVS:ään (Concurrent Versioning System), mikä merkitsee sitä, että täytyy olla teknisesti taitava päästäkseen lähdemateriaalin kimppuun ja parantelemaan sitä.
Tämä järjestelmä ei ota huomioon tosiasiaa, että tekniset kirjoittajat eivät ole ohjelmoijia. Teknisillä kirjoittajilla on yleensä erilainen työkalulaatikko, he eivät ole tottuneita tyypillisiin ohjelmoijien työkaluihin. Oletus siitä, että vapaan dokumentaation kirjoittajat käyttävät CVS:n kaltaista työkalua sisällöntuotantoon on samanlainen virhe, kuin oletus, että dokumentaation lukijat tietävät enemmän kuin tietävät: teknisten kirjoittajien kynnyksen asettaminen liian korkealle merkitsee, että monet ihmiset, jotka voisivat kirjoittaa dokumentaatiota, eivät tee niin.
Ei ole olemassa syytä vangita sisältö CVS:ään. Olemme tekemisissä tekstin ja kuvien kanssa, on olemassa paljon työkaluja, joita on helpompi käyttää. Suosittelen wikiä, jossa on WYSIWYG (What You See Is What You Get, sen saat mitä näet) -editori. Nämä editorit näyttävät tekstinkäsittelyohjelmilta ja toimivat samalla tavalla, mutta ovat käytettävissä kaikkialla, jossa pääset verkkoon selaimellasi. En suosittele merkintäkielten käyttöä, koska jopa wikien merkintäkieli on hankalampi kuin WYSIWYG -editorit, mikä on este kirjoittajille.
Monet projektit asentavat nyt rakenteettomia wikejä kehittäjilleen ja käyttäjilleen pohjaksi dokumentaation kehittämiselle. Tällä hetkellä mediawikiä käytetään usein, vaikkakin tietyn alustan valinta riippuu usein ohjelmistomuodin tuulista. Nämä resurssit voivat olla erittäin hyviä, kuitenkin uskon rakenteettomaan wiki-sisällön, kontekstuaalisella navigaatiojärjestelmällä, olevan huono vaihtoehto hyvän rakenteen omaavalle sisällölle, jolla on selkeä huipputason indeksi. Rakenteeton sisältö on hyvä toissijainen dokumentaatiostrategia ja varmasti hyödyllistä dokumentoitaessa vanhanaikaisten käyttöliittymien tai outojen laitteistokonfliktien yksityiskohtia, kuitenkaan se ei korvaa sisältöä, joka on suunniteltu dokumentoimaan ohjelmat kokonaan selkeällä ja rakenteisella tavalla.
Olen havainnut, että kehittäjien kirjoittama dokumentaatio voi tehdä yksinkertaisen perusvirheen: dokumentoida miten ohjelman pitäisi toimia, eikä miten ohjelma toimii. Vapaata dokumentaatiota ei pitäisi kirjoittaa ulkomuistista. Sellaisten henkilöiden, jotka eivät näe ongelmia, ei pitäisi kirjoittaa dokumentaatiota.
On oikein ja välttämätöntä kertoa käyttäjälle ohjelman ongelmista, mikä ohjelmassa ei toimi ja mitä voitaisiin parantaa. Ei ole huonoa mainosta vapaalle ohjelmalle kertoa oudosta yksityiskohdasta, jota ei pitäisi olla olemassa. On paljon suurempi ongelma, jos lukija lukee dokumentaatiota, joka ei pidä paikkaansa, tai jos dokumentaatio sivuuttaa nämä ongelmat.
Dokumentaation pitäisi houkutella lukemaan. Vuosien aikana vapaiden ohjelmistojen kehittäjät ovat huomanneet, että käyttöliittymän pitää toimiakseen näyttää kauniilta ja olla selkeä ja miellyttävä käyttäjän silmälle. Sama pitää paikkansa dokumentaation suhteen. Musta teksti sinisillä linkeillä valkoisella taustalla ei ole esteettistä. Pyri ulkoasuun, joka parantaa luettavuutta, mutta varmista, että se myös näyttää hyvältä.
Nyt tapaamme kummituksen. Laatu. Mikä on laadukasta dokumentaatiota? Joitain mittareita:
ei kirjoitusvirheitä
tee tyyliopas ja käytä sitä
askelia ei jää pois välistä
dokumentaatio vastaa todellisuutta
Pelkän proseduurin lisäksi on olemassa laadun subjektiivinen määritelmä. Ei ole selkeitä sääntöjä, parasta minkä voit tehdä on saada ihmiset lukemaan sisältö ja kertomaan, että se tuntuu järkevälle. Jos kuulut kirjoittajien yhteisöön, yritä saada muut kirjoittajat katsomaan tekstiäsi.
Ennen kuin puhumme enemmän FLOSS Manualsin yrityksistä ratkaista tässä mainitut ongelmat, tahdon kertoa hieman tarpeesta luoda vapaan dokumentaation sektori.
Vapaat ohjelmistot ovat luoneet metodologian ja talouden, joka vapaalta dokumentaatiolta puuttuu. Perinteinen tapa tehdä rahaa käyttöopasbisneksessä on kirjoittaa käyttöopas ja myydä sitä. Etujen suojaamiseksi käytetään tavanomaista "suljettua" tekijänoikeuksien julistusta. Tämä on julkaisumalli. Tämän yksityisomisteisen sisällön piirin ulkopuolella voidaan pyrkiä tekemään dokumentaatiota vapaaehtoisesti ja julkaista se verkossa mahdollisuuksien mukaan.
Vapaiden ohjelmistojen sektorilla on paljon paremmat resurssit käytössään. Vapaat ohjelmistoprojektit ovat luoneet toimivia malleja ja joukon sisältö- ja hallintatyökaluja, joihin sisältyy kehitys- ja jakelusivustot, kuten Savannah ja SourceForge. Rahoitusmalli on myös paljon selkeämpi. Rahan tekeminen vapaiden ohjelmien projektien parissa vaatii parantamaan taitoja ja etsimään yrityksen, joka maksaa tehdystä työstä.
Vapaasta dokumentaatiosta puuttuu kaikki nämä komponentit - ei ole tyypillistä teknistä työkalupakkia, on hyvin harvoja vapaan dokumentaation kirjoittajien "yhteisöjä" ja vähemmän mahdollisuuksia saada vuokra maksettua, jos kirjoittajat päättävät tehdä tätä täyspäiväisesti. Meidän on tärkeää löytää tapa rakentaa nämä elementit, jos tahdomme terveen vapaan dokumentaation sektorin kehittyvän, ja tahtoisin väittää, että tämä on välttämätöntä myös vapaiden ohjelmistojen saamiseksi laajaan käyttöön. On välttämätöntä, että löydämme ja kehitämme nämä mallit ja työkalut, koska suljetun dokumentaation perusmalli sisältää ideologisen paradoksin.
Meidän täytyy rakentaa vapaan dokumentaation ympärille ekologia samaan tapaan kuin vapaiden ohjelmistojen sektori on tehnyt. Vapaat ohjelmistot antavat ohjelmoijien työskennellä yhteisöissä työkaluilla, jotka mahdollistavat yhteistyön, ja tilaisuuden oppia kollegoiltaan.
Näissä yhteisöissä toimii maineen taloustiede, joka vahvistaa parhaita toimintotapoja, ja onnekas vähemmistö voi käyttää mainettaan saadakseen palkkaa vapaiden projektien parissa työskentelemisestä.
Vapaa dokumentaatio tarvitsee työkaluja, yhteisöjä ja taloutta. Vapaan dokumentaation täytyy identifioida itsensä sektorina ja rakentaa tietoisuus yhteisönä. Tämä itsessään voi johtaa parempaan dokumentaatioon ja mahdollisuuteen saavuttaa taloudellisesti kestävä toimintamalli ihmisille, jotka tahtovat elää kirjoittaen vapaita käyttöoppaita.
On olemassa muutamia pinnallisia myyttejä dokumentaatiosta. Nämä myytit häiritsevät jonkin verran sektorin kehitystä. Ensimmäisen myytin mukaan dokumentaation kirjoittaminen on tylsää. Se voi olla tylsää, mutta se voi myös olla hyvin tyydyttävää, ja se voi varmasti olla hauskaa. Olen tosiaankin nähnyt ihmisten olevan onnellisia ja ylpeitä käyttöoppaistaan ja innostuneita, kun joku tulee mukaan ja parantelee oppaita. Tuntuuko tutulta? Se on hieman kuin vapaiden ohjelmistojen sektori. Kyllä, tekniset kirjoittajat nauttivat työstään, he nauttivat hyvin tehdystä työstä, he nauttivat taitojensa kehittymisestä, he nauttivat saamastaan tunnustuksesta, ja he nauttivat erityisesti, kun ihmiset hyötyvät heidän työstään.
On myös toinen myytti, joka täytyy puhkaista. Olen nähnyt tietyn määrän jahkailua, kun vapaiden ohjelmien maailma pohtii vapaisiin käyttöoppaisiin kirjoittamista. Tämä tuntuu johtavan ohjelmoijien uskomuksesta, jonka mukaan kirjan kirjoittaminen on vapaiden ohjelmien talouden peruskivi. Ei ole miellyttävää kertoa tätä uutista, mutta kustannusmaailma on käymässä läpi samaa valtavaa haastetta tälle tuotemallille, kuin muut teollisuudenalat, joiden tuotetta kritisoidaan.
Ei niinkään, että yksityisomistuksessa olevaan sisältöön ja tiedon myyntiin luottavat kirjamarkkinat olisivat koskaan tehneet teknisille kirjoittajille paljon rahaa, mutta suurempi ongelma on mukana pelissä. Monet eivät näe, että kustannusmaailma on muuttunut. Ei ole kyse vain ohjelmista, musiikista ja elokuvista, jotka kiertävät keinotekoiset jakelun esteet - kirjatkin tekevät niin. Jos ohjelmoijat pitävät kiinni vanhanaikaisesta yksityisomistuksessa olevan tiedon uudelleenmyynnistä, he menettävät toissijaisen tulonlähteensä. Uusi malli on, kuten tekninen kirjoittaja Janet Swisher sanoo, "laskuttaa ajasta, mutta antaa tuotteet pois."
Tekniset kirjoittajat ovat yleisemminkin samassa tilanteessa. On täysin mahdollista saada toimeksianto kirjoittaa käyttöoppaita tai olla töissä yrityksessä kirjoittamassa talon sisäisiä tukidokumentteja, jotka voidaan myös antaa suurelle yleisölle vapaalla lisenssillä. Kuten tässä esimerkissä, monissa tapauksissa vapaan dokumentaation talous voi kartoittua suoraan vapaiden ohjelmistojen ympärille luodun talouden päälle. Voidaan väittää, että ohjelmat ovat jo olemassa, mutta dokumentaatiota ei ole, joten potentiaalinen kysyntä on hyvin korkea.
There has been error in communication with Booktype server. Not sure right now where is the problem.
You should refresh this page.