Tämä lokalisoitu versio keskittyy aiheeseen Building a Simple PDF Document from Scratch ja käyttää päivitettyä englanninkielistä artikkelia teknisenä perustana Delphi-, PDF- ja dokumenttiohjelmistotiimeille
Sivu muuntaa päivitetyn pohja-artikkelin konkreettisiksi tarkistuspisteiksi suunnittelua, toteutusta ja validointia varten
Mitä englanninkielisestä artikkelista synkronoitiin
Englanninkielistä pohja-artikkelia on laajennettu käytännön kontekstilla, teknisillä päätöksillä ja konkreettisilla esimerkeillä, joten tätä sivua kannattaa lukea työohjeena eikä lyhyenä yhteenvetona
Päivitetyn pohja-artikkelin tärkeät osat:
- Käytä ensin pieniä toistettavia syötetiedostoja
- Pidä tuotenimet, API-nimet, tiedostonimet ja literal-arvot muuttumattomina
- Tallenna validatorin tuloste ja versiotiedot luodun esimerkkitiedoston kanssa
Käytännön toteutusvalinnat
Aloita tiedostotyypistä, odotetusta tuloksesta ja virhetilasta, jonka käyttäjän pitää nähdä. Sido sen jälkeen jokainen API-kutsu tarkistettavaan tulokseen, jotta validointi, lokitus ja tuki voivat toistaa asiakkaan tilanteen
- Käytä ensin pieniä toistettavia syötetiedostoja
- Pidä tuotenimet, API-nimet, tiedostonimet ja literal-arvot muuttumattomina
- Tallenna validatorin tuloste ja versiotiedot luodun esimerkkitiedoston kanssa
Tarkistus ennen julkaisua
Tarkista tulostiedosto samoilla työkaluilla, joita asiakas tai arkisto käyttää. Kirjaa komponenttiversio, testidata, validatorin versio ja havaittu tulos, jotta myöhempi regressio voidaan jäljittää täsmällisesti
Täydentävä tekninen tarkastelu
Tämä laajennettu osio liittyy artikkeliin Tekninen artikkeli: Building a Simple PDF Document from Scratch suomeksi ja avaa saman työketjun siltä kannalta, että tiimin pitää voida jäljittää myöhemmin sekä generoinnin, validoinnin että lokituksen päätökset. Linkitetyn sivun englanninkielinen perusartikkeli hreflangin kautta näyttää, miksi pelkkä otsikoiden kääntäminen ei riitä; olennaista on selittää, miksi asiakirja on valmis vasta silloin, kun säännöt, tulos ja tarkastusjäljet on oikeasti sovitettu yhteen
Toteutusta käsittelevissä artikkeleissa on hyödyllistä erottaa suunnittelu ja tarkistus toisistaan. Ensin määritetään tiedostotyyppi, odotettu tulos ja käyttäjän näkemä virhetila, ja sen jälkeen jokainen API-kutsu sidotaan tulokseen, jonka voi toistaa samassa skenaariossa. Tämä pätee sekä PDF- että taulukkolaskentatyöhön: koodiesimerkit säilyvät muuttumattomina, mutta ympäröivän tekstin pitää selittää, miksi komponenttiversio, mallin tunnus, syötedata ja validointitila kannattaa kirjata yhteen
Yhtä tärkeää on säilyttää tuotenimet, API-nimet, tiedostonimet ja literal-arvot täsmälleen kuten englanninkielisessä lähteessä. Se pitää kehityksen, tuen ja laadunvarmistuksen yhteisen viitekehyksen kasassa ja vähentää riskiä siitä, että paikallisesta versiosta tulee vain vapaa parafraasi ilman täsmällistä teknistä sisältöä. Jos artikkelissa on koodia, kommenttien ja tokenien tulee pysyä koskemattomina, koska juuri ne yhdistävät tekstin todelliseen projektiin
Kun sivua luetaan julkaisun jälkeen, siitä kannattaa ajatella jäljitettävää ketjua. Hyvä validointimerkintä kuvaa, mitä testattiin, millä työkalulla tulos arvioitiin, mitkä versiot olivat mukana ja minne todiste onnistumisesta tai epäonnistumisesta on tallennettu. Kun myöhemmin ilmenee regressio, arkistoitu raportti ja siihen liittyvä syötetiedosto ovat paljon arvokkaampia kuin pelkkä muisto siitä, että "se meni silloin läpi"
Tälle lokalisoidulle haaralle pätee siis yksinkertainen sääntö: pidä keskeiset päätökset, tarkistuspisteet ja koodin konteksti yhdessä, jotta artikkeli on hyödyllinen paitsi ensimmäisellä lukukerralla myös myöhemmässä virheenjäljityksessä, auditoinnissa ja versioiden vertailussa. Se on ero lyhyen yhteenvedon ja työasiakirjan välillä, jolla on arvoa vielä useiden julkaisutusten jälkeen.
- Käytä ensin pieniä toistettavia syötetiedostoja
- Pidä tuotenimet, API-nimet, tiedostonimet ja literal-arvot muuttumattomina
- Tallenna komponenttiversio, validatorin tulos ja syötetiedot yhdessä
- Säilytä koodilohkot ja kommentit täsmälleen kuten lähteessä
Lisähuomiot tarkistusta varten
Laajemmissa artikkeleissa, kuten Tekninen artikkeli: Building a Simple PDF Document from Scratch suomeksi, on hyödyllistä kuvata myös se, miten tekstiä käytetään myöhemmässä tarkastuksessa. Lukijan pitäisi nähdä, että keskeiset päätökset eivät ole irrallaan todisteista: samat syötetiedostot, sama komponenttiversio, sama validatori ja sama raportti. Kun nämä pidetään yhdessä, on myöhemmin helppo päätellä, syntyikö ongelma generoinnissa, validoinnissa vai vasta tuloksen arkistoinnissa
Käytännössä kannattaa kirjata ylös myös pienet yksityiskohdat, jotka ensimmäisessä toteutuksessa katoavat helposti. Tällaisia ovat mallin nimi, ajon tunnus, päivämäärä, kirjaston versio ja täsmällinen työkalu, joka arvioi tuloksen. Sivun koodilohkot pysyvät muuttumattomina, mutta juuri tämä tukiteksti selittää, miksi ne ovat tärkeitä auditoinnille ja tuelle ja miksi API-nimet, tiedostonimet ja literal-arvot eivät saa kadota lopullisesta aineistosta
Sama periaate pätee myös julkaisun jälkeisiin korjauksiin. Kun virheellinen tai kiistanalainen kohta pitää avata uudelleen, auttaa vain teksti, joka näyttää, mitä syötettä käytettiin, mitä odotettiin, mitä oikeasti mitattiin ja missä todiste säilytetään. Siksi sivulla on hyvä olla paitsi pääselitys myös selkeä lisäosa, joka sitoo päätökset tarkistuspisteisiin ja jättää sekä lukijalle että tukitiimille selkeän jäljen
- Säilytä API-, tiedosto- ja literal-nimet täsmälleen ennallaan
- Kirjaa komponentti- ja validatoriversio jokaisen tarkistuksen yhteyteen
- Käytä regressiossa samoja syötteitä ja samaa raporttia