Diátaxis. տեխնիկական փաստաթղթավորման գրելու համակարգային մոտեցում

Diátaxis-ը տեխնիկական փաստաթղթավորման հեղինակման համակարգային մոտեցում է։ Հեղինակ Դանիելե Պրոչիդան այն ներկայացնում է որպես փաստաթղթավորման մասին մտածելու և այն անելու եղանակ. այն սահմանում է մոտեցումներ բովանդակությանը, ճարտարապետությանը և ձևին, որոնք բխում են փաստաթղթավորման օգտատերերի կարիքների ուսումնասիրությունից։

Փաստաթղթավորման չորս տեսակ

Հիմնական գաղափարն այն է, որ գոյություն ունեն չորս սկզբունքորեն տարբեր տեսակի փաստաթղթեր, որոնք պատասխանում են չորս տարբեր կարիքների՝ ուսումնական ձեռնարկներ (tutorials), գործնական ուղեցույցներ (how-to guides), տեղեկատու (reference) և բացատրություններ (explanation)։ Յուրաքանչյուրն ունի իր նպատակը և պետք է գրվի այլ կերպ։ Ձեռնարկը դաս է, որը սովորողին ձեռքից բռնած տանում է ուսումնական փորձի միջով. այն միշտ գործնական է, ինչպես վարելու դասը։ Գործնական ուղեցույցը դիմում է արդեն բավական փորձառու օգտատիրոջը և օգնում հասնել իրական նպատակի կամ լուծել խնդիր. այն աշխատանքի մասին է, ոչ թե սովորելու։ Տեղեկատուն պարունակում է տեխնիկական փաստեր, որոնք անհրաժեշտ են ճիշտ գործելու համար՝ ճշգրիտ, ամբողջական և առանց մեկնաբանության, ինչպես ծովային քարտեզը։ Բացատրությունը տալիս է համատեքստ ու նախադրյալներ, կապում է իրերը և պատասխանում «ինչու» հարցին։

Քարտեզ և կողմնացույց

Diátaxis-ը չորս տեսակները դասավորում է հայեցակարգային քարտեզի վրա և ավելացնում կողմնացույց, որը օգնում է որոշել՝ կոնկրետ նյութը որտեղ պետք է տեղադրվի։ Ձեռնարկներն ու ուղեցույցները վերաբերում են այն բանին, թե ինչ է անում օգտատերը՝ գործողությանը, իսկ տեղեկատուն ու բացատրությունները՝ այն բանին, թե ինչ գիտի օգտատերը՝ ճանաչողությանը։ Ձեռնարկներն ու բացատրությունները ծառայում են հմտության ձեռքբերմանը՝ սովորելուն, իսկ ուղեցույցներն ու տեղեկատուն՝ հմտության կիրառմանը՝ աշխատանքին։ Ըստ նախագծի հեղինակների՝ հենց այդ սահմանների հատումը կամ լղոզումն է ընկած փաստաթղթավորման հսկայական թվով խնդիրների հիմքում։

Փորձով ապացուցված

Մոտեցումը ներկայացվում է որպես թեթև, հեշտ ընկալելի և տեխնիկական սահմանափակումներ չպարտադրող, և այն հաջողությամբ կիրառվել է հարյուրավոր փաստաթղթավորման նախագծերում։ Vonage-ի Գրեգ Ֆրիլյոն ասում է, որ Diátaxis-ի շնորհիվ ստեղծվել է բարձրորակ ներքին փաստաթղթեր. Մեգան Սալիվանը պատմում է, որ Gatsby նախագիծը բաց կոդով փաստաթղթերը վերակազմակերպելիս հենվել է այս շրջանակի վրա, իսկ չորս քառորդները օգնել են առաջնահերթություններ դասել, իսկ Ադամ Շվարցը հիշում է, որ Cloudflare-ի մշակողների փաստաթղթերը վերանայելիս Diátaxis-ը դարձավ «մեր տեղեկատվական ճարտարապետության ուղեցույց աստղը»։

Ինչպես սկսել

Կայքի սեփական խորհուրդը՝ սկսել կիրառելով՝ ինչ-որ բանի վրա, թեկուզ ամենափոքրի։ Առաջարկվող աշխատանքային ցիկլը հետևյալն է. նայել ձեր առջև եղած փաստաթղթերին, հարցնել՝ հնարավո՞ր է այն ինչ-որ կերպ բարելավել, ընտրել մեկ բան, որ կարող եք անել հենց հիմա, և անել այն, ապա կրկնել։ Տեսությանը հավատալ պարտադիր չէ. հեղինակն այն ներկայացնում է որպես զուտ պրագմատիկ մոտեցում, որի արժեքը մարդկանց ավելի լավ փաստաթղթեր ստեղծելու հարցում օգնելն է։