Dokumentaatiotiimit julkaisevat Markdownia harvoin vain yhteen kohteeseen. Dokumentti voi alkaa luonnoksena muistiinpanosovelluksessa, siirtyä GitHub-repositoriooon ja mukautua sen jälkeen CMS:ään, tietopankkiin tai tuotteen sisäiseen ohjepintaan. Sama sisältö voi selviytyä useista renderöijistä ennen kuin lukija näkee sen. Siksi dokumentaation laadunvarmistus tarvitsee enemmän kuin nopean raakatekstin silmäilyn.
Convertyn Markdown-validaattori on hyödyllinen juuri julkaisemista edeltävässä ikkunassa. Se antaa dokumentaation omistajan tarkistaa renderöidyn lopputuloksen ja rakennevaroitukset, jotka voivat piiloutua sisältöön, joka näyttää ensisilmäyksellä hyväksyttävältä. Tämä on eri asia kuin täysi dokumentaatiobuildi, ja sen pitääkin olla eri asia.
Markdown-tarkistus epäonnistuu, jos kaikki kohteet oletetaan samanlaisiksi
Markdownista on helppo puhua yhtenä formaattina, jolla on yksi lopputulos. Käytännössä dokumentaatiotyö on täynnä kohdekohtaisia odotuksia. GitHubin README renderöityy yhdessä kontekstissa. CMS-lohko tai dokumentaatioalusta voi renderöidä sen toisessa. Vaikka syntaksi on suurimmaksi osaksi yhteinen, pienten virheiden seuraukset vaihtelevat pinnan mukaan.
Siksi dokumentaatiotarkistuksen pitää alkaa lähteestä, mutta se ei saa olettaa lähteen olevan koko tarina. Otsikoiden pitää toimia. Linkkien pitää osoittaa johonkin todelliseen. Kuvilla pitää olla alt-tekstiä. Koodilohkoilla pitää olla riittävä konteksti. Validaattori on hyödyllinen, koska se löytää hiljaiset ongelmat ennen kuin kohderenderöijästä tulee ensimmäinen vakava tarkistaja.
Kuinka löydät Markdown-ongelmat ennen julkaisua on Convertyn Markdown-QA:n perusviite. Dokumentaatiotiimin versio on sama työnkulku suuremmilla seurauksilla.
Dokumentaatiotarkistuksen pitää vastata kahteen kysymykseen
Jokaisen Markdown-passin pitää vastata yhteen visuaaliseen ja yhteen rakenteelliseen kysymykseen. Visuaalinen kysymys on: näyttääkö dokumentti siltä kuin lukijan pitäisi odottaa? Otsikot katkeavat oikeissa kohdissa, listat pesiytyvät siististi, koodilohkot pysyvät koodina ja sivu etenee siinä järjestyksessä kuin tarkoitit.
Rakenteellinen kysymys on toinen: onko dokumentti tarpeeksi terve selvitäkseen seuraavasta handoffista? Pelkkä esikatselu ei riitä. Sivu voi renderöityä tarpeeksi hyvin ja sisältää silti otsikkohyppyjä, tyhjiä linkkejä, puuttuvia kuvien alt-tekstejä tai nimeämättömiä koodilohkoja. Dokumentaatiotyössä nämä merkitsevät enemmän, koska sisältöä voidaan kopioida, kääntää, renderöidä muualla tai ylläpitää ihmisten toimesta, jotka eivät kirjoittaneet alkuperäistä.
Käytännön docs-työnkulku on lyhyempi kuin täysi ympäristöbuildi
Kuvittele dokumentaatiotiimi, joka valmistelee päivitettyä asennusopasta. Sivulla on otsikoita, koodiesimerkki, kuvakaappaus ja ristiinlinkkejä vanhempiin artikkeleihin. Lopullinen kohde on repositorio ja CMS-pohjainen dokumentaatiopinta. Tiimi tarvitsee myöhemmin kohdetietoisen tarkistuksen, mutta siellä ei kannata löytää ilmeisiä lähdevirheitä.
Tehokkaampi järjestys on:
- Liitä luonnos Markdown-validaattoriin.
- Lue renderöity sivu läpi ensikertalaisen lukijan näkökulmasta.
- Korjaa otsikkorakenteeseen, linkkeihin, kuviin ja koodilohkoihin liittyvät varoitukset.
- Kopioi puhdistettu versio repositorioon tai CMS:ään.
- Tee lopullinen tarkistus kohteessa vain renderöijäkohtaiselle käytökselle.
Jos dokumentaatiopäivitys on osa laajempaa julkaisua, Kuinka sisältötiimit valmistelevat slugit, Markdownin ja faviconit uutta julkaisua varten asettaa Markdown-validoinnin osaksi isompaa julkaisutarkistuslistaa.
GitHub ja CMS rankaisevat eri laiskuuksia
GitHub on yhdessä mielessä anteeksiantava ja toisessa ei. Se renderöi usein dokumentin, vaikka rakenne olisi heikko, jolloin Markdown tuntuu "ihan hyvältä". CMS-työnkulku voi tehdä päinvastoin: se hyväksyy liitoksen, mutta heikko lähderakenne muuttuu myöhemmin kivuliaaksi, kun sisältöä pitää muokata, migroida tai käyttää uudelleen.
Siksi validointi ennen julkaisua ei ole parserin miellyttämistä. Se suojaa dokumenttia tulevalta kitkalta. Jos otsikot ovat sotkuisia, seuraava toimittaja perii epäselvyyden. Jos linkit ovat tyhjiä tai virheellisiä, kohde on ensimmäinen paikka, jossa virhe huomataan. Jos kuvien alt-teksti puuttuu, saavutettavuus heikkenee hiljaa.
Raaka HTML pitää käsitellä varovasti
Dokumentaatiotiimit perivät usein Markdownia, jossa on pieniä HTML-fragmentteja. Ne voivat tulla vanhasta CMS-viennistä, layout-kiertoteistä tai nopeasti lisätyistä release- tai incident-muokkauksista. Tämän todellisuuden sivuuttaminen ei auta.
Työnkulku tarvitsee esikatselun, joka on tarpeeksi lähellä kohdetta ollakseen hyödyllinen, mutta ei liian salliva tai turvaton. Validaattorin sanitoitu esikatselumalli auttaa tarkistamaan realistisemman renderöintipassin ilman, että jokaiseen liitettyyn HTML-fragmenttiin pitää luottaa sokeasti.
Tässä myös Ovatko online-muuntimet turvallisia työtiedostoille? on relevantti. Dokumentaatioluonnokset sopivat usein selainpohjaiseen tarkistukseen, mutta arkaluonteinen sisäinen materiaali vaatii yhä harkintaa.
Validoi lähde ennen kuin kohde joutuu selittämään sen sinulle
Dokumentaatioalustat ovat hyviä valmiin työn julkaisuun, eivät perusauthoroinnin virheiden debuggaamiseen. Hyödyllisempi tapa on validoida Markdown silloin, kun se on vielä lähdettä.
Avaa Markdown-validaattori suoraa pre-publish-tarkistusta varten, käytä usein kysyttyjä kysymyksiä laajempaan työnkulkumalliin, palaa Markdown-QA:n perusoppaaseen ja yhdistä tämä artikkeli turvallisuuspohdintaan, kun todellinen päätös on, milloin selainpohjainen sisältötarkistus on oikea valinta.
