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

    Článek: AN0002369Aktualizováno:: 06.11.2018

    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/';
    }

×