Tämä lokalisoitu versio keskittyy aiheeseen Understanding PDF File Structure: A Technical Overview 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: Understanding PDF File Structure: A Technical Overview 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ä