Případová studie: Verzovaná dokumentace - Migrace

V tomto článku si popíšeme migraci původní dokumentace k systému ObjectGears do nové Verzované dokumentace. Původní dokumentace byla uložena v souborech na disku a již nevyhovovala zcela potřebám.
Proto jsme vyvinuli novou dokumentaci, která má několik výhod:

• lze ji prohledávat
• je založena na systému ObjectGears a je možné ji tedy dále volně vylepšovat a rozšiřovat
• přístup je řízen pomocí rolí
• umožňuje více verzí jednoho článku
• jednoduše logujeme přístupy a neplatné odkazy
• podpora tagů, jazykových lokalizací, archivace starých článků
• podpora pro editory s identifikací článků vyžadujících pozornost
• podpora zálohování přes databázi

 

Migraci jsme rozfázovali do několika kroků.

1. příprava - záloha staré dokumentace a instalace nové instance ObjectGears s modelem Verzovaná dokumentace
2. import - import souborů s texty do databáze
3. pročištění dat
4. finální instalace dokumentace na provozní server a zveřejnění

1. Příprava
Prvním krokem bylo vytvoření zálohy staré dokumentace, aby bylo se k čemu vrátit a případně dohledat články. To se vždy vyplatí, protože při jakékoli migrace nemusí vždy vše proběhnout, jak by si člověk naplánoval.

Nejprve jsme zkontrolovali soubory s články a promazali ty, které byly dříve vytvořeny, ale neměly obsah. Tím jsme určili soubory, které měly být zmigrovány.
Do nového řešení bylo také třeba přesunout obrázky, které původně byly v rootu webové aplikace. Cílem bylo přenést je do podadresáře webu instance ObjectGears ImagesData, aby se nimi dalo v ObjectGears pracovat. Zároveň jsme vytvořili nový adresář Images_1710, kam jsme nakopírovali všechny obrázky z verze 1.7.1.0. Na ně jsme pak (v kroku 3) přesměrovali všechny odkazy ze všech článků, které se odkazovaly na obrázky v původní složce Images. Jelikož nová dokumentace běží v ObjectGears, tak není vhodné se přímo odkazovat do adresáře Images, protože nová verze ObjectGears může přinést nové obrázky v této složce a to by mělo vliv na články o starších verzích. Pro budoucí verze ObjectGears budeme vytvářet nový podadresář, abychom zajistili odkazy na správné obrázky pro danou verzi.

 

2. Import
Pro import jsme použili funkcionalitu z Administračního nástroje, která umožňuje importovat do třídy soubory a to obrázkové nebo textové. V našem případě jsme importovali textové soubory.

Soubory jsme neimportovali přímo do cílových tabulek, ale do pomocných tříd. Ty obsahovaly sloupce pro vlastní importovaná data a další sadu sloupců pro informace o jazyku, verzi, id tématu a id nadřízeného článku. Ty jsme po importu pomocí připravených SQL skriptů postupně doplnili a to včetně odkazů mezi články.

Jeden importovaný soubor pak představuje jeden až dva záznamy v cílových třídách. Jeden do článku a druhý do textu_článku. Soubory pro jiné jazyky pak vkládají záznam jen do textu_článku. To byl další důvod použití pomocných tříd. Všem článkům jsme nastavili jazyk a napevno verzi 1.7.1.0.

Po kontrole dat v pomocných třídách jsme vytvořili skript, který články vložil do cílových tříd pro článek a text_článku. Importovaný text jsme vložili do dvou sloupců: do Nového a Zveřejněného textu. Nakonec jsme importovali i hierarchie článků - vztah článku k nadřízenému článku.

Vazby "Viz také" , které propojují články mezi sebou pomocí odkazů na konci článku, jsme neimportovali. Důvodem bylo málo záznamů k importu, a tak jsme je po migraci doplnili ručně přes GUI. Bylo to jednodušší  a rychlejší než připravovat i tato data k migraci. Zároveň tuto práci mohl provést někdo jiný než vývojáři a dala se udělat paralelně.

Zatímco vývojáři připravovali a ladili migrační skripty, další kolegové kontrolovali soubory pro import a výsledky z testování importu. když jsme byli všichni spokojeni, provedli jeme konečný import. Pak jsme se již k původním souborům nevraceli.

3. Pročištění dat
Po importu následovalo čištění dat. V prvním kroku jsme pro hlavní články nastavili odkaz na téma. Pro ostatní (podřízené) články jsme zkontrolovali, zda jsou správně zařazené.

Z migrace nám vypadlo cca 30 článků, které byly vytvořeny, ale nebyly nikde zařazeny. Ve staré dokumentaci jsme na toto nepřišli. V nové dokumentaci lze takovéto články ihned vyfiltrovat. Nově takovéto články ani nemohou vzniknout.

Se změnou dokumentace bylo potřeba změnit URL v odkazech mezi články. Tuto změnu jsme provedli updatem v databázi - nahrazením staré adresy Help.aspx?h= za novou ./-vcd/_jazyk_/. Následně jsme otestovali všechny odkazy prostým proklikáním. Tak jsme identifikovali cca 50 chybně napsaných odkazů, které jsme opravili.

Při kontrole jsme nalezli několik stránek v anglické verzi, které nebyly celé přeloženy. Patrně je někdo dříve rozšířil, ale někde se nám ztratila informace o tom, aby byly přeloženy. Nastavili jsme jim tedy příznak pro překlad a budou průběžně přeloženy.
V tom spočívá jedna z výhod nového systému. Stačí jen nastavit příznak a není třeba nikomu nic psát. Články označené příznaky nebo identifikované na základě určité logiky se zobrazují automaticky v přehledech pro editory.

Skriptem v databázi jsme také z článku odstranili nadpis článku. Ten je nově uložen odděleně od článku ve sloupci třídy text_článku a vkládá se automaticky do stránky.

4. Finální nasazení
Po kontrole a dopsání všech článků a posledním vyladění modelu s Verzovanou dokumentací následoval přesun vlastní databáze na provozní server s poslední verzí 1.8.0.0 (v době migrace ještě neveřejnou).

Jako poslední krok jsme přidali přesměrování ze staré URL Help.aspx?h=... na novou  vcd/... , aby fungovaly původní odkazy a odkazy z google a seznamu. Nastavili jsme permanentní redirect, aby nedošlo k penalizaci ze strany Google za přesměrovávání.

Příklad skriptu pro přesměrování:

if ( OGErrorInfo.IsInvalidPage && OGErrorInfo.Request.Url.AbsolutePath.ToLower().Contains('help.aspx'))
{
  OGErrorInfo.RedirectPermanent = true;
  OGErrorInfo.RedirectToUrl = './vcd/en-us/' + OGErrorInfo.Request.QueryString['h'] + '/v/1.7.1.0/';
}