Diátaxis: texniki sənədləşmə yazmağa sistemli yanaşma

Diátaxis texniki sənədləşmənin yazılmasına sistemli yanaşmadır. Müəllifi Daniele Procida onu sənədləşmə haqqında düşünməyin və sənədləşmə ilə məşğul olmağın bir yolu kimi təqdim edir: məzmuna, arxitekturaya və formaya dair yanaşmalar sənədləşmə istifadəçilərinin ehtiyaclarının öyrənilməsindən doğur.

Sənədləşmənin dörd növü

Əsas fikir budur ki, dörd fərqli ehtiyaca cavab verən dörd əsaslı fərqli sənədləşmə növü mövcuddur: təlimatlar (tutorials), how-to bələdçiləri, arayış sənədləri (reference) və izahlar (explanation). Hər birinin öz məqsədi var və hər biri fərqli şəkildə yazılmalıdır. Təlimat şagirdi öyrənmə təcrübəsi boyunca əlindən tutub aparan dərsdir; o həmişə praktikdir, sürücülük dərsi kimi. How-to bələdçisi artıq səriştəli olan istifadəçinin real məqsədə çatmasına və ya problemi həll etməsinə yönəlir; işlə bağlıdır, təhsillə deyil. Arayış sənədləri düzgün iş görmək üçün lazım olan texniki faktları ehtiva edir: dəniz xəritəsi kimi dəqiq, tam və şərhsiz. İzah isə kontekst və məlumat verir, hissələri bir-birinə bağlayır və “niyə” sualına cavab verir.

Xəritə və kompas

Diátaxis bu dörd növü konseptual xəritədə yerləşdirir və konkret materialın hara aid olduğunu müəyyən etməyə kömək edən kompas əlavə edir. Təlimatlar və how-to bələdçiləri istifadəçinin etdiyi işlərlə — fəaliyyətlə, arayış və izahlar isə istifadəçinin bildikləri ilə — idrakla bağlıdır. Təlimatlar və izahlar bacarıq qazanmağa, yəni öyrənməyə xidmət edir; how-to bələdçiləri və arayış isə bacarığın tətbiqinə, yəni işə. Layihəyə görə, məhz bu sərhədlərin pozulması və ya bulanıqlaşdırılması sənədləşmədəki saysız-hesabsız problemlərin mərkəzində dayanır.

Təcrübədə sübut olunub

Yanaşma yüngül, anlamaq asan və texniki məhdudiyyətlər qoymayan bir üsul kimi təqdim olunur; prinsipləri yüzlərlə sənədləşmə layihəsində uğurla tətbiq edilib. Vonage-dən Greg Frileux deyir ki, Diátaxis sayəsində yüksək keyfiyyətli daxili sənədlər yaradılıb; Megan Sullivan bildirir ki, Gatsby layihəsi açıq mənbə sənədlərini yenidən təşkil edərkən bu çərçivəyə arxalanıb və dörd kvadrant sənəd növlərini prioritetləşdirməyə kömək edib; Adam Schwartz isə xatırladır ki, Cloudflare developer sənədləri yenidən hazırlanarkən Diátaxis “informasiya arxitekturamızın bələdçi ulduzu”na çevrilib.

Necə başlamalı

Saytın öz məsləhəti belədir: tətbiq etməklə başlayın — nə qədər kiçik olsa da bir şeyə. Tövsiyə olunan iş dövrü budur: qarşınızda olan sənədlərə baxın, onu bir şəkildə yaxşılaşdırmaq mümkün olub-olmadığını soruşun, elə indi edə biləcəyiniz bir şeyi seçin və onu edin; sonra təkrarlayın. Nəzəriyyəyə inanmaq lazım deyil: müəllif bunu tamamilə praqmatik bir yanaşma kimi təqdim edir və dəyərinin insanlara daha yaxşı sənədlər yaratmağa kömək etməsində olduğunu deyir.