Documentație scrisă înainte de îmbinare

O pagină de documentație este un set de afirmații despre cod. Sună evident până observați că nimic din procesul de construcție nu verifică vreuna dintre ele. Testele afirmă lucruri despre cod. Verificările de tipuri afirmă lucruri despre cod. Proza despre cod afirmă lucruri despre cod și este verificată de o persoană care o citește o singură dată, în ziua în care a fost scrisă.

Am scris două pagini noi de documentație într-o singură rundă: una pentru editorul de automatizări, în jur de 2930 de cuvinte englezești pe opt secțiuni, și una pentru tabloul de bord, în jur de 909. Plus o secțiune adăugată la două pagini care existau deja. Două propoziții de pe pagina de automatizări erau deja false când a fost publicată.

Nimeni nu scrisese un neadevăr. Ambele propoziții erau exacte față de ramura pe care fuseseră scrise.

Propoziția care era adevărată când a fost scrisă

Documentația unei funcții se scrie de obicei după funcție, ceea ce înseamnă că se scrie în timp ce alte ramuri sunt încă deschise. A noastră așa a fost. Pagina descria un nod de notificare și spunea, în esență, că acesta nu trimite e-mail. Față de ramura pe care fusese scrisă, asta era exact: nodul scria o notificare în panou și nimic nu pleca din clădire.

O rundă paralelă s-a îmbinat prima și a dat nodului o casetă pentru e-mail, oprită implicit, o categorie proprie de dezabonare și o regulă potrivit căreia o rulare de test nu trimite niciodată nimic. Fiecare dintre aceste fapte este interesant pentru un cititor. Niciunul nu se afla pe pagină, iar ce se afla pe pagină spunea acum contrariul.

A doua propoziție descria felul în care un plan se leagă de un flux. Spunea că planul rulează fluxul din spatele lui, dintr-o vreme în care acea relație era unu la unu. Aceeași îmbinare a înlocuit-o cu o joncțiune: un plan poate atârna cel mult un flux pe moment, din trei momente, iar un flux declanșat manual sau prin webhook nu poate atârna acolo deloc. „Nu poate fi atașat” este un răspuns mai bun decât „atașat și nu face nimic în tăcere”, dar este un răspuns diferit, iar pagina îl dădea încă pe cel vechi.

Reparația a fost mică. Partea interesantă este felul în care a fost găsită: cineva s-a dus să caute dinadins, fiindcă o rundă care atinge un subiect este singurul moment în care cineva are un motiv să recitească proza despre acel subiect.

Ce poate prinde o gardă

Există un al doilea mod de eșec pe aceleași pagini și, spre deosebire de primul, acesta se poate mecaniza.

Pagina tabloului de bord are un tabel cu cardurile pe care le poate adăuga un utilizator. Acele carduri au nume, în nouă limbi, iar acele nume există deja: sunt etichetele din selectorul pe care utilizatorul chiar dă clic. A scrie un tabel de documentație înseamnă a le scrie a doua oară.

A mers prost imediat, la prima ciornă, în engleză:

Niciuna dintre acestea nu este greșită ca engleză. Toate trei sunt greșite ca documentație, fiindcă un cititor căruia i se spune să adauge „Connections” va căuta un card numit Connections și va găsi un card numit Integration list. Abaterea este tăcută prin construcție: ambele texte sunt în regulă în sine, iar nimeni nu pune un manual lângă un selector.

Așa că tabelul preia acum aceleași chei de catalog pe care le preia selectorul, iar un test cere ca ele să fie identice cuvânt cu cuvânt în toate cele nouă limbi. Cheia de documentație este derivată din identificatorul cardului și nu este enumerată de mână, astfel încât al șaptelea card opțional pe care îl adaugă cineva la anul să fie măsurat fără ca nimeni să își amintească să îl treacă aici. Aceasta este aceeași formă ca garda pe care o rulăm între cele două copii ale mesajelor de server în engleză și există din același motiv: două locuri care păstrează un singur adevăr au nevoie de un test care să spună asta, nu de o convenție.

Numele butoanelor de pe aceeași pagină au fost ghicite în cinci din cele nouă limbi. Acum vin și ele din catalog. Iar trei limbi traduseseră cuvântul Scripts, care este numele unui element de meniu ce nu se traduce în produs, așa că pagina spunea unui cititor spaniol, portughez și ucrainean să dea clic pe ceva ce nu există sub acel nume.

Un token tehnic nu este un cuvânt

Numele de produse, porturile, căile, numele de module și codurile de stare stau într-un token cu spațiere fixă și rămân în engleză, oriunde apar, în orice limbă. Regula nu este nouă. Nou a fost că scrierea ei în aceste pagini s-a lovit dintr-odată de alte două gărzi.

A pune un element <code> literal într-un tablou de rânduri de tabel declanșează regula de lint care vrea o cheie pe fiecare element JSX dintr-un tablou, chiar și aici, unde componenta de tabel învelește fiecare celulă în propriul element cu cheie și cheia nu este citită niciodată. A-i pune o cheie declanșează o altă gardă, care vede un copil cu cheie stând lângă apeluri de traducere ale căror chei nu le poate rezolva în acel fișier.

Ieșirea a fost o funcție de o linie care întoarce elementul. Pentru regula de lint este un apel de funcție și nu un element de tablou; pentru cealaltă gardă nu este o cheie. Rezultatul desenat este identic octet cu octet. Este un lucru mic și este genul de lucru mic care se rezolvă cu un comentariu de dezactivare atunci când nimeni nu consemnează de ce cele două reguli nu s-au înțeles.

Capturi de ecran care păreau reușite

Măsurătoarea pentru aceste pagini a cuprins capturi de ecran pe ancore: se derulează până la fiecare secțiune, se fotografiază, se privește.

Nouă dintre ele arătau antetul paginii.

Comanda de browser care surprinde o regiune dincolo de fereastra vizibilă își calculează decupajul de la începutul documentului, nu de la poziția curentă de derulare. Derulați până la o ancoră aflată la opt ecrane mai jos, cereți o regiune la coordonatele pe care le raportează elementul și fotografiați în schimb începutul paginii, exact la dimensiunea corectă, într-un fișier cu numele corect. Fiecare dintre acele capturi era o imagine plauzibilă a lucrului greșit.

Adăugarea decalajului curent de derulare a rezolvat-o. Forma generală este una pe care o tot întâlnim: o măsurătoare care eșuează producând un rezultat cu aspect normal este mai rea decât una care se prăbușește, fiindcă prăbușirea este cercetată în aceeași zi.

Partea la care nu ajunge nicio gardă

Numele cardurilor se puteau mecaniza fiindcă ambele părți sunt șiruri într-un singur depozit. Cele două propoziții învechite nu se puteau, și merită să fim preciși de ce, fiindcă este tentant să credem că orice problemă de documentație are un test care așteaptă să fie scris.

O propoziție care spune că un nod nu trimite e-mail este o afirmație despre un comportament răspândit în patru fișiere, o valoare implicită, o casetă de bifat și o listă de categorii. Nu există nicio expresie cu care să o comparați. Singurul mecanism care ar prinde-o este un test care desenează comportamentul și citește propoziția, adică un test care trebuie scris pentru fiecare propoziție, de cineva care știe deja că propoziția este greșită.

Ce am făcut în schimb a fost mai ieftin și merită numit ca practică: când s-a făcut corectura, întregul subarbore de documentație a fost căutat după orice altă afirmație despre e-mail și orice altă afirmație despre un flux pe plan. Nu exista un al treilea loc. Acesta este un rezultat, nu o formalitate. Fără el, runda ar fi reparat două propoziții și l-ar fi lăsat pe cititor cu convingerea rezonabilă că pagina fusese verificată.

Aceeași disciplină există deja în altă parte în acest proiect pentru o altă pereche: articolele noastre lungi se pot învechi față de lista integrărilor aflate în producție, iar nimic nu se face roșu când se întâmplă. Două articole au petrecut odată șase săptămâni spunând că doi hipervizori erau pe foaia de parcurs, deși amândoi erau deja livrați. Regula ieșită de acolo este aceeași: dacă o rundă schimbă statutul unui lucru, căutați numele lui în proză.

Ce am consemna

1. 01Proza despre cod este o afirmație netestată. Nimic din procesul de construcție nu o citește. Asta este în regulă, atâta vreme cât toată lumea o știe și nimeni nu presupune că o rulare verde spune ceva despre paragraf.
2. 02Documentația se scrie față de o ramură, nu față de main. Dacă alte runde sunt deschise, pagina este un instantaneu al unei stări care s-ar putea să nu ajungă niciodată în producție. Recitiți-o după îmbinare, nu înainte.
3. 03Un nume care există în produs trebuie citit, nu rescris. Trei din șase nume de carduri s-au abătut la prima ciornă. În nouă limbi asta este o clasă de eroare, nu un accident.
4. 04Derivați cheia de documentație din identificator. Atunci cardul următor este acoperit fără ca nimeni să își amintească regula aceasta.
5. 05Un cuvânt ghicit într-o limbă pe care nu o citiți este invizibil. Cinci limbi aveau nume de butoane ghicite și nimic nu era roșu.
6. 06Traducerea unui nume de produs este o instrucțiune stricată. Dacă meniul spune Scripts în orice limbă, manualul spune Scripts în orice limbă.
7. 07Când două reguli de lint nu se înțeleg, consemnați pe care ați ascultat-o și de ce. Alternativa este un comentariu de dezactivare pe care nimeni nu îl mai poate cântări mai târziu.
8. 08O măsurătoare care produce un rezultat plauzibil când eșuează nu va fi pusă la îndoială. Fotografiați ceva ce puteți recunoaște și uitați-vă la poze.

Ca să fie limpede ce este aceasta: ambele pagini sunt în producție în nouă limbi, cele două propoziții învechite au fost corectate în toate cele nouă, iar garda peste numele cardurilor este în suită și a fost dovedită roșie înainte să fie dovedită verde. Afirmațiile de pe pagini vin din citirea codului și nu din rularea lui; exemplul cu curl de pe pagina de automatizări nu a fost trimis către un endpoint viu; iar fiecare traducere a avut un singur cititor, nu doi.

Din munca de platformă la Provibr. Cardurile la care se referă acele nume se află în o scurtătură este o referință, nu un drept, iar cât costă să ții cinstite nouă cataloage se află în șaisprezece mii de chei, nouă limbi.