Dokumentatsioonitiimid avaldavad Markdowni harva ainult ühte sihtkohta. Dokument võib alata mustandina märkmerakenduses, liikuda GitHubi reposse ja seejärel kohanduda CMS-i, teadmistebaasi või tootesisese abi pinna jaoks. Sama sisu võib enne lugejateni jõudmist läbida mitu renderdajat. Seetõttu vajab dokumentatsiooni kvaliteedikontroll enamat kui kiiret toorallika silmitsust. Küsimus pole ainult selles, kas Markdown on kehtiv. Küsimus on selles, kas dokument on üleandmiseks valmis.
Converty Markdowni valideerija on kasulik just selles aknas enne avaldamist. See laseb docs'i omanikul renderdatud tulemust üle vaadata ja kontrollida struktuurihoiatusi, mis sageli peidavad end sisus, mis esmapilgul näib veel aktsepteeritav. See erineb täielikust docs'i build'ist ja peakski erinema. Eesmärk on tabada levinud autorivead enne, kui sisu jõuab raskematesse süsteemidesse, kus vigu on raskem isoleerida.
Markdowni ülevaatus ebaõnnestub, kui docs'i tiimid kohtlevad kõiki sihtkohti identsena
Markdownist on lihtne rääkida nii, nagu see oleks üks vorming ühe järjepideva tulemusega. Praktikas on dokumentatsioonitöö täis sihtkohaspetsiifilisi ootusi. README GitHubis on ühes renderduskontekstis. CMS-plokk või docs'i platvorm võib olla teises. Isegi kui süntaks on suuresti ühine, erinevad väikeste vigade tagajärjed pinniti.
Seetõttu peab docs'i ülevaatuse harjumus algama allikast, kuid mitte eeldama, et allikas on kogu lugu. Pealkirjad peavad endiselt loogilised olema. Lingid peavad endiselt päriselt kuhugi viitama. Piltidel peab endiselt olema alt-tekst. Koodiplokkidel peab olema piisavalt konteksti, et järgmine süsteem saaks neid selgelt renderdada või taaskasutada. Validaator on kasulik just seetõttu, et tabab vaiksed probleemid enne, kui sihtkoha renderdaja saab esimeseks tõsiseks ülevaatajaks.
Seetõttu jääb Kuidas leida Markdowni probleeme enne avaldamist Converty Markdown QA baasviiteks. Docs'i tiimi versioon probleemist on sama töövoog suuremate tagajärgedega: rohkem sisu, rohkem taaskasutust ja vähem taluvust välditavate struktuurivigade suhtes.
Dokumentatsiooni ülevaatus peaks vastama kahele eri küsimusele
Iga avaldamiseelne Markdowni pass peaks vastama ühele visuaalsele ja ühele struktuurilisele küsimusele.
Visuaalne küsimus on lihtne: kas dokument näeb välja nii, nagu lugeja seda ootaks? See tähendab, et pealkirjad murduvad seal, kus plaanisid, listid pesastuvad puhtalt, koodiplokid jäävad koodiplokkideks ja leht loeb samas järjekorras, nagu arvasid selle kirjutavat.
Struktuuriline küsimus on teine: kas dokument on piisavalt terve, et järgmine üleandmine üle elada? Eelvaade üksi ei saa sellele täielikult vastata. Leht võib renderduda piisavalt hästi, kuid sisaldada pealkirjahüppeid, tühje linke, puuduvaid pildi alt-tekste või keelemärgiseta koodiplokke. Need probleemid loevad docs'i töös rohkem kui juhuslikus sisus, sest dokumenti võidakse kopeerida, tõlkida, mujal renderdada või hooldada inimeste poolt, kes ei kirjutanud originaali.
Seetõttu vajab validaator mõlemat poolt. Eelvaade ütleb, kuidas lugeja mustandit praegu kogeb. Hoiatused ütlevad, mis tõenäoliselt katki läheb, halvasti vananeb või raskemini hooldatavaks muutub, kui sisu liigub edasi.
Praktiline docs'i töövoog on lühem kui täielik keskkonnabuild
Oletame, et dokumentatsioonitiim valmistab ette uuendatud seadistusjuhendit. Lehel on mitu pealkirja, koodinäide, ekraanitõmmis ja ristlingid vanematele artiklitele. Lõplik sihtkoht on repo koos CMS-toega docs'i pinnaga. Tiim vajab hiljem ikka täielikku sihtkohateadlikku ülevaatust, kuid see pole õige koht ilmselgete allikaprobleemide avastamiseks.
Tõhusam jada on:
- Kleebi mustand Markdowni valideerijasse.
- Loe renderdatud leht algusest lõpuni nagu esmakordne kasutaja.
- Paranda pealkirjade, linkide, piltide ja koodiplokkidega seotud hoiatused.
- Kopeeri puhastatud versioon reposse või CMS-i.
- Tee sihtkohas lõplik pass ainult renderdajaspetsiifilise käitumise jaoks.
See töötab, sest eraldab levinud autorivead sihtkohaspetsiifilistest iseärasustest. Validaator käsitleb universaalsed probleemid esimesena ja jätab lõppülevaatuse keskenduma päriselt pinnaspetsiifilistele asjadele.
Kui docs'i uuendus on osa laiemast lansseerimisest, on Kuidas sisutiimid saavad uueks lansseerimiseks valmistada slugid, Markdowni ja faviconid laiem operatsiooniline kaaslane. See asetab Markdowni valideerimise tagasi suuremasse avaldamise kontrollnimekirja.
GitHubi ja CMS-i handoffid karistavad eri liiki laiskust
GitHub on ühtpidi andestav ja teistpidi andestamatu. See renderdab dokumendi sageli isegi siis, kui struktuur on nõrk, mis teeb lihtsaks eeldada, et Markdown on "korras". CMS-i töövood võivad tekitada vastupidise probleemi. Need võivad kleepimise vastu võtta, kuid nõrk allikastruktuur muutub hiljem valusamaks, kui keegi peab sisu muutma, migreerima või taaskasutama.
Seetõttu pole avaldamiseelne valideerimine niivõrd parseri rahustamine, vaid dokumendi kaitsmine tulevase hõõrdumise eest. Kui pealkirjad on lohakad, pärib järgmine toimetaja segaduse. Kui lingid on tühjad või vigased, saab sihtkoht esimeseks kohaks, kus viga märgatakse. Kui pildi alt-tekst puudub, langeb ligipääsetavus vaikselt. Kui koodiplokil puudub keelekontekst, muutub leht vähem kasutatavaks just seal, kus lugeja vajab selgust.
Docs'i tiimid tunnevad neid probleeme teravamalt, sest nende sisu elab kauem kui lansseerimiscopy. Blogipostitus võib avalduda ja vananeda. Seadistusjuhend või tugiartikkel peab hooldust üle elama.
Toorest HTML-i tuleb käsitleda hoolikalt, mitte ignoreerida
Dokumentatsioonitiimid pärivad sageli Markdowni, mille sees on väikseid HTML-fragmente. Mõnikord tulid need vanast CMS-i ekspordist. Mõnikord kleepiti need sisse paigutuse või vorminduslünkade lahendamiseks. Mõnikord lisati need kiiresti intsidendi või release'i ajal ja neid ei puhastatud kunagi.
Selle reaalsuse ignoreerimine ei aita. Docs'i töövoog vajab eelvaadet, mis on sihtkohale piisavalt lähedal, et olla kasulik, ilma muutumata ebaturvaliseks või liiga lubavaks. See on üks põhjus, miks validaatori puhastatud eelvaatemudel loeb. See laseb tiimil realistlikumat renderduspasse kontrollida, teesklemata, et iga kleebitud HTML-fragment peaks olema pimesi usaldatud.
Siin muutub asjakohaseks ka laiem käsitlusjuhis artiklist Kas veebikonverterid on tööfailide jaoks turvalised? Mida kontrollida enne kleepimist või üleslaadimist. Dokumentatsioonimustandid sobivad sageli brauseriutiliidi jaoks. Tundlik sisematerjal vajab endiselt otsustusvõimet. Tööriist peaks ülevaatust toetama, mitte usalduspiiri rohkem laiendama, kui ülesanne väärib.
Hea docs'i ülevaatuspass vähendab tulevast muutmiskulu
Kõige odavam Markdowni parandus on see, mis tehakse enne, kui fail jõuab kohta, kus mitu süsteemi või inimest sellest sõltuvad. Docs'i tiimide jaoks pole see ainult avaldamismugavus. See on hoolduse eelis. Puhtamat lähtefaili on lihtsam üle vaadata, uuendada, lokaliseerida ja vaikse lagunemiseta töös hoida.
Seetõttu tuleks avaldamiseelset validaatorit lugeda toimetamiskulu vähendajana, mitte ainult süntaksikontrollina. See aitab luua dokumendi, mis elab üle nii järgmise renderdaja kui ka järgmise toimetaja.
Valideeri allikas enne, kui sihtkoht peab seda sulle tagasi selgitama
Dokumentatsiooniplatvormid on head kohad valmis töö avaldamiseks, mitte head kohad põhiliste autorivigade debugimiseks. Kasulikum harjumus on valideerida Markdowni siis, kui see on veel lihtsalt allikas.
Ava Markdowni valideerija otseseks avaldamiseelseks ülevaatuseks, kasuta korduma kippuvaid küsimusi laiemate töövoo ootuste jaoks, vaata uuesti Kuidas leida Markdowni probleeme enne avaldamist põhivalideerimismustri jaoks ja ühenda see artikkel tekstiga Kas veebikonverterid on tööfailide jaoks turvalised? Mida kontrollida enne kleepimist või üleslaadimist, kui päris otsus puudutab seda, millal brauseripõhine sisukontroll on õige valik.
