Fjarmiðjuhandbókin

Ég hef farið um netið í leit að upplýsingum um ýmiss tölvumálefni en oft gengið brösuglega að finna vel skrifuð skjöl um það sem ég vil fræðast.  Yfirleitt er um að ræða hugbúnað frá stórum fyrirtækjum hverra nafn skiptir ekki máli.

Ég ætla í nerdagírinn og tala um skjölun.

Þeir sem eiga að skrifa handbækur eru oft orðnir svo samdauna vinnunni að þeir geta ekki lengur lýst henni á prenti fyrir ókunnugum, sennilega af því þeir geta ekki sett sig í spor óreyndra og af því þeir hafa ekki heyrt spurningarnar sem upp koma hjá þeim, hafandi ekki unnið í notendaþjónustu eða við kennslu á hugbúnaðinum.

Oft virðist höfundur ekki hafa skilgreint fyrir sjálfum sér hver lesandinn sé, áður en hann sest við skriftir.  Stundum hef ég á tilfinningunni að sá sem skrifar gefi sér að lesandinn viti þetta allt og það sé hálf vandræðalegt að þurfa að lýsa kerfinu.

Það er algengt að hugtök séu notuð án þess að þau séu skilgreind fyrst.  Einnig er algengt að kaflar geti ekki staðið sjálfstætt vegna óteljandi tilvísana út og suður innan skjalsins og í önnur skjöl.  Tilvísanir eru í lagi  - upp að vissu marki.

Þetta hefur ágerst eftir að netið kom, því sumir handbókahöfundar telja sig undanþegna því að skipuleggja frásögn sína, því alltaf megi hoppa á eftir næsta "hyperlink" ef lesandinn þarf að fylla út í söguþráðinn.

Hjá mörgum fyrirtækjum tíðkast að láta nýja starfsmenn skrifa handbækur því lengra komnir starfsmenn vilja helst sleppa.  Nýliðar vita oft lítið um kerfin og geta ekki leyft sér að trufla forritarana við vinnu sína til að spyrja heimskulegra spurninga - sem eru í raun ekki heimskulegar.

Nýliðarnir reyna að sleppa billega með því að skrifa texta sem lýsir kerfinu mjög yfirborðslega, án þess að lýsa nokkurn tímann hvað kerfið gerir.  (Sumir gárungar kenna þetta heilkenni við Microsoft).

Oft byrjar handbókin mjög lofandi eins og ef yfirmaður hafi setið hjá nýliðanum fyrsta klukkutímann en svo rennur hún út í sandinn.  Stundum virðast handbækurnar vera lítið annað losaraleg dagbók yfir breytingar á kerfinu í gegnum árin, eins konar glósur fyrir höfundana sjálfa, en ekki leiðbeiningar fyrir notendur.

Það er vandi að skrifa handbók, en þegar hún eru góð getur verið unun að lesa hana.

---

Hér er í lokin ímyndaður kafli úr nútíma handbók sem ég ætla til viðvörunar, ekki eftirbreytni.  Hann inniheldur flesta þá hluti sem ég var að skrifa um.


Inngangur

Kæri notandi!

Við óskum þér til hamingju með kaupin.  Fjarmiðja ehf. hefur sérhæft sig í gerð vandaðra fjarmiðja sem standast ítrustu kröfur sem gerðar eru og við erum viss um að nýja fjarmiðjan þín á eftir að sinna hlutverki sínu um ókomin ár.

 

 

 

 

 

 

 

 

 

 

 

Kafli 1  Fjarmiðjur

Þessi kafli fjallar um fjarmiðjur.  Kaflinn kemur í staðinn fyrir eldri lýsingar á fjarmiðjum.  Eftir útgafu þessarar handbókar er Fjarmiðja hf ekki ábyrg gagnvart skemmdum sem verða vegna óviðeigandi lýsinga í eldri bókum á fjarmiðjum (eða hjámiðjum).

Kaflinn skiptist í undirkafla sem hér segir:

1.0: kynning
1.1: litlar fjarmiðjur
1.2: stórar fjarmiðjur
1.3: notkun á fjömiðjum

1.0: Kynning

Lýsingu á  eldri fjarmiðjum er hægt að fá í fjórða kafla eldri handbókar um fjarmiðjur: "Nýjar fjarmiðjur 2006: meðferð og viðhald" (2006) og hægt er að panta hjá þjónustuveri.

(ATHUGIÐ: Fjarmiðjur fyrir sleskjur eldri en sex ára verða ekki þjónustaðar eftir janúar 2008).

Þessi  kafli lýsir hvað fjarmiðjur eru, hvers vegna sleskjur fyrir fjarmiðjur slitna hraðar en eðlilegt þykir og hvað hægt er að gera til að uppfæra eldri fjarmiðjur til samræmis við nýrri vörur frá Fjarmiðju hf.

(Nánari lýsingar á fjarmiðjum fyrir lengra komna eru einnig í köflum 7: sleskjur með svarfsöfnurum, 11: minni sleskjur með hjámiðju og 13: svarfsafnara skipt út í nýrri fjarmiðjum).

Í hverri fjarmiðju er svæði fyrir sleskjur og sleskjusvarfi er safnað í svarfsafnara (merktur med rauðu "B" undir eldri fjarmiðjum eða grænu "S" í nýrri fjarmiðjum).

Boðið er upp á þrenns konar fjarmiðjur:

• Fjarmiðjur med stuðningi fyrir nýjar og eldri sleskjur
• Fjarmiðjur án stuðnings fyrir eldri sleskjur en stærri svarfsafnara
• Fjarmiðjur med áföstum sleskjum (verða ekki þjónustaðar eftir janúar 2008).

   

Um slit á sleskjum

Slit á sleskjum verður þegar fjarmiðja er of stór fyrir sleskjur eða þegar gömul sleskja er sett a svæði í nýrri fjarmiðju sem er ætluð fyrir nýjar sleskjur.  Mikilvægt er að fylgjast með slitinu, sjá aftast í undirkafla 4.1 þar sem fjallað er um viðauka C.

1.1 litlar fjarmiðjur

Litlar fjarmiðjur eru þær fjarmiðjur sem hafa stuðning við fjórar eða færri sleskjur. 

Hægt er að uppfæra litlar fjarmiðjur fyrir stuðning við fimm eda fleiri sleskjur, en mælt er med því að stórar fjarmiðjur séu keyptar ef til stendur ad nota fleiri en átta sleskjur.  Litlar fjarmiðjur eru teknar upp i nýjar fjarmiðjur samkvæmt taxta enda sé slit á fjarmiðjunni undir mörkum (sjá viðauka A:  Viðmiðunarverð a fjarmiðjum 2007 og viðauka C: slitstuðlar fyrir Fjarmiðjur i notkun 1989-2006).  Athugið að verðskráin gildir aðeins til desember 2007.

1.2 stórar fjarmiðjur

Stórar fjarmiðjur ráða við fimm eða fleiri sleskjur.  Séu sleskjurnar eldri en þriggja ára má koma tveim sleskjum fyrir á svæði sem ætlað er fyrir nýrri gerð af sleskjum en gæta verður að því að fjarmiðjan ofhitni ekki eða svarfsafnari offyllist.

1.3 notkun á fjarmiðju (loksins lærir maður eitthvað!?)

Inngangur

Stórar og litlar fjarmiðjur hafa sömu notendaskil.  Á þeim eru þrír takkar að ofanverðu.


Takkar á fjarmiðju

Takkar á fjarmiðju eru merktir: "Sleskja tengd", "Sleskja aftengd" og "Svarfsöfnun á/af".  Þeim verður nú lýst.

• [SLESKJA TENGD]
  Ýtið á takkann til að tengja sleskju.  Sé ýtt oftar en einu sinni heyrist aðvörunarhljóð.  Varast skal að halda takkanum inni því sleskjan getur ofhitnað.
• [SLESKJA AFTENGD]
  Ýtið á takkann til að aftengja sleskju.  Sé ýtt oftar en einu sinni heyrist aðvörunarhljóð en óhætt er að halda takkanum inni enda er sleskjan augljóslega ekki nálægt fjarmiðjunni.
• [SVARFSÖFNUN Á/AF]
  Ýtið á þennan takka til að kveikja og slökkva á svarfsöfnun.

---

Ég vona að þið séuð einhverju nær um sleskjur og fjarmiðjur, en ég óttast samt að þið séuð búin að ákveða að fjarmiðjur séu eitthvað sem þið hafið ekki vit á og best sé að láta sérfræðinga um að annast þær fyrir ykkur.

Kveðja, Kári

PS:  Ég sé að það er fljótlegt að skrifa handbækur.  Ein A4 síða komin á 25 mínútum!

 

 

 

Athugasemdir

[Einar Indriðason, 8.10.2007 kl. 21:54]

"Frábær" handbók.  Mjög fljótlesin, og því miður eins og þú segir, allt of innihaldslaus til að gagnast að viti.

Takk samt

[Lana Kolbrún Eddudóttir (IP-tala skráð) 9.10.2007 kl. 19:30]

Mér finnst að þú ættir að lesa þetta upp í útvarpið. Massívur texti...

[Anna Ólafsdóttir Björnsson, 9.10.2007 kl. 21:50]

Úpps, ég er mikil áhugakona um skjölun í öllum kimum tölvuheimsins og handbókagerð sömuleiðis (þrátt fyrir næstum sjö ára starf innan hugbúnaðargeirans), en svona lesning gerir mann auðvitað nánast fullkomlega fráhverfan öllu slíku. 

[Kári Harðarson, 10.10.2007 kl. 06:30]

Mark Twain byrjaði bréf til vinar síns með orðunum:  Fyrirgefðu hvað bréfið er langt en ég hef ekki tíma til að skrifa þér stutt bréf.

Það er fljótlegt að henda saman miklum texta en svo kostar yfirlegu að gera hann stuttann og hnyttinn.

Lengdin er hluti af vandmálinu...  Ein uppáhalds handbókin er upphaflega bókin um forritunarmálið C.  Ég hef séð tífalt þykkari bækur um valmyndir í Windows.

[Einar Indriðason, 10.10.2007 kl. 08:06]

... og með ca. 1000 sinnum minna innihald heldur en K&R?