Info Draft FLOSS Manuals suomeksi

Tekninen kirjoittaminen

On tarpeeksi helppoa osoittaa mikä on väärin ja selittää miten asioiden pitäisi olla. On toinen asia tehdä asioille jotain. Tehdäkseni asialle jotain perustin FLOSS Manualsiksi kutsutun säätiön, joka ei pyri voiton tuottamiseen. Olemme vapaan dokumentaation kirjoittajien yhteisö. Pyrimme kirjoittamaan loistavaa dokumentaatiota vapaista ohjelmistoista. Kuka tahansa voi liittyä FLOSS Manualsiin ja jokainen voi muokata julkaisemaamme materiaalia. Kaikki sisältö on lisensöity vapaan lisenssin alla (GPL, GNU General Public Licence).

Kun aloitimme (aloitimme virallisesti lokakuussa 2007), yhteistyössä tapahtuvalle tekniselle kirjoittamiselle ei ollut, eikä ole vieläkään, hyviä julkaisualustoja. Jotkut voisivat väittää, että CMS-ohjelmia (Content Management Systems) on jo liikaa, ja varmasti jokin CMS sopii tarpeisiimme?

Itse asiassa ei sovi. Mitä lähemmäs yhteistyössä toimivaa julkaisua pyritään, sitä kauemmas useimpien CMS-ohjelmien toiminnallisuudesta päädytään. Joten olemme hakkeroineet ihmeellisen TWikin ja kehittäneet omat lisäosamme. TWiki on osoittautunut hyväksi alustaksi verkkojulkaisulle. Sillä on kaikki rakenteellisen sisällön ominaisuudet ja käyttäjien hallinta, joka tekee siitä hyvän alustan sisällön tuottamiseen yhteistyössä. Mikä puuttuu, ja mikä puuttuu muista CMS-ohjelmista, on hyvä tekijänoikeuksien ja kirjoittajien jäljitys, helpot tavat rakentaa sisällysluetteloja ja siisti tapa uudelleenmiksata sisältöä. Me olemme korjanneet tämän nyt omilla lisäosillamme (saatavilla TWikin säilöstä).  

Uudelleenmiksaus

Sana "uudelleenmiksaus" on voinut kiinnittää huomiosi ja olet ehkä ihmetellyt "käyttöoppaiden remiksausta". Se ei välttämättä näytä ymmärrettävältä ensisilmäyksellä, mutta on olemassa paljon hyviä syitä, joiden vuoksi käyttöoppaat ovat loistavaa materiaalia uudelleenmiksaukseen. En tarkoita uudelleenmiksausta William S. Burroughsin cut-up-tekniikan mielessä - kannatamme lineaarisuutta vapaan dokumentaation maailmassa. Tarkoitan remiksausta monien lukujen yhdistelemisenä monista eri käyttöoppaista, jolloin muodostetaan uusi dokumentti. Tämän tekeminen auttaa käyttäjää luomaan käyttöoppaan, joka sopii heidän tarpeisiinsa riippumatta siitä, onko kyse itseopiskelusta, luokkien opettamisesta vai talon sisällä tapahtuvista opetusohjelmista.

Englanninkielisen FLOSS Manualsin uudelleenmiksaustoiminto (http://www.flossmanuals.net/remix) mahdollistaa sisällön uudelleenmiksaamisen sisällysluettelolla varustettuihin PDF-tiedostoihin ja ladattaviin HTML-tiedostoihin, joihin voit luoda käyttöoppaan ulkoasun käyttämällä Cascading Style Sheetsiä. Nyt olemme myös lisänneet Remix Application Programming Interface -käyttöliittymän. Tämä merkitsee sitä, että voit uudelleenmiksata käyttöoppaita ja liittää ne verkkosivullesi leikkaamalla ja liimaamalla muutaman rivin HTML-koodia. Ei ole enää tarpeen sählätä FTP-tiedostonsiirron kanssa. Tämä osa FLOSS Manualsista on uusi ja vain englanninkielisen puolen testikäytössä, mutta toistaiseksi se on toiminut hyvin. Remiksauksen yhdistäminen tarvittaessa painamisen kanssa on ilmeinen seuraava askel. Se voidaan tehdä nyt, koska painopalvelut käyttävät PDF-tiedostoja lähdemateriaalinaan, mutta merkittävämpi temppu on saada se näyttämään hyvältä paperilla.

Sananen uudelleenmiksauksesta - jos tahdot tehdä teknistä dokumentaatiota, joka on käytettävissä uudestaan, niin ajattele miten kirjoitat sen. On hyvä idea pitää dokumentaatio modulaarisena - ilman riippuvuuksia muuhun sisältöön ja käyttäen mahdollisimman vähän vain yhteen asiayhteyteen liittyvää kieltä.

Tarvittaessa painaminen

Ilmaisten verkossa olevien käyttöoppaiden lisäksi englanninkielisen FLOSS Manualsin materiaali muutetaan kirjoiksi "paina tarvittaessa" -palvelun avulla. Nämä kirjat ovat kivan näköisiä, koska niitä on muuteltu painoa varten, ja ne ovat saatavilla kustannushintaan. Englanninkielisellä FLOSS Manualsilla on myös oma verkkosivuille liitettävä kirjakauppavimpain (http://www.flossmanuals.net/bookstore). Kuka tahansa, joka tahtoo tukea vapaiden ohjelmistojen leviämistä, voi lisätä FLOSS Manuals -kirjakaupan verkkosivulleen lisäämällä muutaman lyhyen rivin HTML-koodia.

Kun puhun ihmisille, olen huomannut, että fyysiset käyttöoppaat ovat paras tapa saada esiteltyä, mitä FLOSS Manuals -projekti tekee. Wikistä puhuminen on toinen juttu, mutta käyttöoppaiden näyttäminen saa ihmiset ymmärtämään asian. Kirjat ovat erinomainen tapa edistää vapaiden ohjelmistojen tuntemusta.

Laadunvalvonta

Lopuksi sananen laadusta. Nämä käyttöoppaat pyrkivät olemaan parempia kuin mikään saatavilla oleva dokumentaatio. Joskus tämä ei ole vaikeaa, koska dokumentaatiota ei ole saatavilla! Monia mielenkiintoisia kysymyksiä nousee esille, kun työskennellään avoimessa järjestelmässä ja ylläpidetään tätä laatutasoa.

Kuka tahansa voi osallistua FLOSS Manualsin luomiseen - se on täysin avoin prosessi. Sinun täytyy rekisteröityä, mutta tämä ei ole yhteistyön portinvartijan toimintaa, vaan tapa noudattaa GPL-lisenssin vaatimusta saada kreditoitua tekijöitä.  Spämmäys on ilmeinen ongelma avoimessa järjestelmässä, kuten on haitallisen tiedon mahdollisuuskin. Väärä tai haitallinen tieto Wikipediassa voi saada sinut puhumaan väärästä Skotlannin kuninkaasta tai voi johtaa sinua harhaan perunoiden alkuperästä puhuttaessa, mutta väärä tieto dokumentaatiossa voi saada sinut tyhjentämään kovalevysi. Olemme siis eristäneet "takaosan" - jossa käyttöoppaita kirjoitetaan - "etuosasta", jossa käyttöoppaita luetaan.

Kirjoita-osassa oleva käyttöopas on jatkuvan kehitystoiminnan kohteina. Kuitenkin sama käyttöopas etusivulla ovat "vakaassa" tilassa, valmiina käytettäväksi. Tämä hoidetaan joillain olemassaolevilla TWiki-työkaluilla, jotka laitoimme yhteen luodaksemme yksinkertaisen yhden askeleen julkaisujärjestelmän. Se toimii näin - jokaisella käyttöoppaalla on ylläpitäjä. Ylläpitäjä on vapaaehtoinen, joka pitää tiettyä käyttöopasta silmällä. Muokkauksia ja päivityksiä voi lisätä Kirjoita-osaan kuka tahansa, joka osaa kirjoittaa. Kun ylläpitäjä uskoo käyttöoppaan olevan hyvässä kunnossa ja päivitys on ajankohtainen, hän painaa Julkaise-nappulaa, ja kaikki materiaali kopioidaan käyttöoppaan "etuosan" versioon. Tällä tavalla lukija saa vakaata ja luotettavaa dokumentaatiota ja kirjoittajat voivat jatkaa dokumenttien kirjoittamista ilman, että lukija joutuisi lukemaan keskeneräistä sisältöä. Se on yksinkertainen ja tehokas järjestelmä.

Kuinka voit auttaa

Hyvä vapaa dokumentaatio ei ole pelkästään hyvän vapaan ohjelman välttämätön osa, se on myös tärkeä osa ohjelmien tuomista suurimman mahdollisen käyttäjäjoukon ulottuville. Vapaa dokumentaatio on samanaikaisesti koulutustyökalu ja markkinointikeino - ilman sitä ohjelmat kasvavat vähitellen, kun käyttäjät kertovat toisilleen, mitä on saatavilla ja kertovat kokemuksistaan ja tiedoistaan toisilleen. Tämä tapahtuu henkilöltä toiselle. Tämä on itsessään voimakas mekanismi, mutta murtautuaksemme tämän muurin läpi keskimääräisen tietokoneen käyttäjän maailmaan tarvitsemme kattavaa ja houkuttelevaa vapaata dokumentaatiota.

Jos rakastat vapaita ohjelmia, liity meihin vapaan dokumentaation tekijöihin! Meillä on kasvava joukko hyvin lahjakkaita kirjoittajia ja ylläpitäjiä. Hyviä käyttöoppaita on saatavilla verkosta, mutta tarvitsemme lisää. Kirjoittaminen on aika helppoa. Jos tahdot olla osa hyvien käyttöoppaiden luomista, rekisteröidy projektiin ja lue käyttöoppaamme FLOSS Manuals -verkkosivulla.

Kuka tahansa voi osallistua: voit kääntää tai kirjoittaa käyttöoppaita, oikolukea niitä, siistiä ulkoasua, testata tai arvostella materiaalia, suunnitella kuvakkeita, ottaa kuvankaappauksia, kirjoittaa, päivittää tai parannella dokumentaatiota. Voit olla avoimien ohjelmien käyttäjä, tekninen kirjoittaja, kuvittaja, ohjelmoija, oikolukija, Linux-guru, wikiharrastaja, ammattimainen dokumentoija tai muuten vain kiinnostunut aihepiiristä. Osallistu millä tahansa sinulle sopivalla tavalla, autat sekä parantamaan dokumentaatiota että levittämään vapaata kulttuuria ja vapaita ohjelmistoja.  

Rekisteröidy tästä: http://fi.flossmanuals.net/register

Miksi käyttäisit FLOSS Manualsia

Jos tahdot kirjoittaa dokumentaatiota vapaata ohjelmistoprojektia varten, ja olet etsimässä yhteisö- ja dokumentaatiotyökaluja, FLOSS Manuals on luotu sinulle. Yleisesti ottaen projektit, jotka käyttävät FLOSS Manualsia, voidaan jakaa kahteen ryhmään:
 
1) FLOSS Manualsin julkaisemat käyttöoppaat
2) Ohjelmistoprojektien kirjoittama "virallinen" dokumentaatio 

FLOSS Manualsin julkaisemat käyttöohjeet

Jos tahdot osallistua FLOSS Manualsin kehittämiseen tai luoda uuden käyttöohjeen, vot yksinkertaisesti luoda käyttäjätunnuksen ja ryhtyä kirjoittamaan. Voit tehdä tämän, jos esimerkiksi löydät käyttöohjeen, joka on linkitetty LUE-osasta (http://fi.flossmanuals.net/lue), ja tahdot laajentaa tai parannella käyttöohjetta. Tämä on tätä kirjoitettaessa yleisin motivaatio FLOSS Manualsin käyttöön.

Ohjelmistoprojektien julkaisema virallinen dokumentaatio

Voi olla, että työskentelet ohjelmistokehitystiimissä, ja etsit dokumentaatioalustaa aloittaaksesi ohjelman "virallisen" dokumentaation kehittämisen. Tässä tapauksessa FLOSS Manuals tarjoaa sinulle wikin, jossa voit kehittää käyttöohjeesi ja hallita sitä itse. Voit käyttää kaikkia tarjolla olevia työkaluja käyttäen FLOSS Manualsin "live manual" -APIa tai linkittämällä PDF-tiedostoon. Voimme myös pitää yllä oman tiimisi kehittämiä mallineita, jolloin voit julkaista staattisia HTML-käyttöoppaita omalla ulkoasullasi ja tuntumallasi

Toivomme myös saavamme "paina tarvittaessa" -prosessin automatisoitua, jolloin voit julkaista kirjan suoraan wikistä "paina tarvittaessa" -palveluun ja määrittää kirjan uudelleenmyyntiarvon itse. Tämä merkitsee, että voit myydä käyttöoppaasi voittoa vastaan hankkiaksesi varaa ohjelmistoprojektillesi. FLOSS Manuals ei pyydä maksua ja emme odota tuloja käyttöoppaidesi myynnistä.

Voit siis päättää, ettet koskaan listaa käyttöopastasi FLOSS Manualsin etusivulla, ja julkaiset pikemminkin käyttöoppaat omalla sivullasi.

Päämäärämme ei ole olla kustantaja, vaan luoda mahdollisimman monta työkalua ja jakelukanavaa vapaalle dokumentaatiolle, joka on mahdollisimman korkeatasoista. Jos tämä merkitsee, että tahdot käyttää FLOSS Manualsin työkaluja, mutta hoitaa palvelinta tai julkaista oman lippusi alla, se käy mainiosti. Olemme hyvin tyytyväisiä tarjotessamme sinulle dokumentaatioalustan, joka palvelee kaikkia dokumentaatiotarpeitasi.

Tämä kaikki on tietenkin vain vapaiden tai avoimen lähdekoodin ohjelmien dokumentaatiolle. Jos luot rajoitetun lisenssin ohjelmia, niin...