Diátaxis — ტექნიკური დოკუმენტაციის წერის სისტემური მიდგომა

Diátaxis ტექნიკური დოკუმენტაციის ავტორობის სისტემური მიდგომაა. მისი ავტორი, დანიელე პროჩიდა, წარმოაჩენს მას როგორც დოკუმენტაციაზე ფიქრისა და მუშაობის ხერხს: ის განსაზღვრავს მიდგომებს შინაარსის, არქიტექტურისა და ფორმის მიმართ, რომლებიც დოკუმენტაციის მომხმარებლების რეალური საჭიროებების შესწავლიდან გამომდინარეობს.

დოკუმენტაციის ოთხი სახეობა

მთავარი იდეა ისაა, რომ არსებობს ოთხი ფუნდამენტურად განსხვავებული სახის დოკუმენტაცია, რომელიც ოთხ სხვადასხვა საჭიროებას ეხმიანება: tutorials (საგაკვეთილო სახელმძღვანელოები), how-to guides (ინსტრუქციები), reference (ცნობარი) და explanation (ახსნა). თითოეულს საკუთარი დანიშნულება აქვს და განსხვავებულ წერის წესს მოითხოვს. სახელმძღვანელო გაკვეთილია, რომელიც მოსწავლეს სასწავლო გამოცდილებაში ხელში ჩაუძღვება — ის ყოველთვის პრაქტიკულია, მაგალითად, მართვის გაკვეთილი. ინსტრუქცია უკვე კომპეტენტურ მომხმარებელს ეხმარება რეალური მიზნის მიღწევაში ან პრობლემის გადაჭრაში; ის შრომაზეა ორიენტირებული და არა სწავლაზე. ცნობარი შეიცავს ტექნიკურ ფაქტებს, რომლებიც სწორად მუშაობისთვისაა საჭირო — ზუსტი, სრული და ინტერპრეტაციისგან თავისუფალი, როგორც საზღვაო რუკა. ახსნა კი კონტექსტსა და ფონს გვაძლევს, აკავშირებს ცალკეულ დეტალებს და პასუხობს კითხვას „რატომ“.

რუკა და კომპასი

Diátaxis ამ ოთხ სახეობას კონცეპტუალურ რუკაზე აწყობს და კომპასსაც სთავაზობს, რომლითაც გადაწყვეტენ, სად უნდა მოხვდეს კონკრეტული მასალა. სახელმძღვანელო და ინსტრუქცია მომხმარებლის ქმედებას (მოქმედებას) ეხება, ცნობარი და ახსნა კი — მომხმარებლის ცოდნას (შემეცნებას). სახელმძღვანელო და ახსნა უნარის შეძენას ემსახურება, ანუ სწავლას, ხოლო ინსტრუქცია და ცნობარი — უნარის გამოყენებას, ანუ მუშაობას. პროექტის მიხედვით, სწორედ ამ საზღვრების გადაკვეთა ან დაბინდვა უდევს საფუძვლად დოკუმენტაციის უმრავლეს პრობლემას.

პრაქტიკაში დამტკიცებული

მიდგომა წარმოდგენილია როგორც მსუბუქი, ადვილად აღსაქმელი და ტექნიკური შეზღუდვებისგან თავისუფალი; მისი პრინციპები ასობით დოკუმენტაციის პროექტშია წარმატებით გამოყენებული. Vonage-ის გრეგ ფრილოს თქმით, Diátaxis-ის წყალობით შიდა მაღალხარისხიანი დოკუმენტაცია შეიქმნა; მეგან სალივანი ამბობს, რომ Gatsby-ის პროექტმა ღია კოდის დოკუმენტაციის რეორგანიზაციისას სწორედ ამ ჩარჩოს დაეყრდნო და ოთხი კვადრატით პრიორიტეტები დაალაგა; Cloudflare-ის ადამ შვარცი კი იხსენებს, რომ დეველოპერებისთვის დოკუმენტაციის გადამუშავებისას Diátaxis „ინფორმაციული არქიტექტურის ჩვენი მეგზური ვარსკვლავი“ გახდა.

როგორ დავიწყოთ

საიტის საკუთარი რჩევა მარტივია: დაიწყეთ გამოყენებით — რაღაცაზე, თუნდაც ძალიან მცირეზე. რეკომენდებული სამუშაო ციკლი ასეთია: შეხედეთ დოკუმენტაციას, რომელიც ახლა თქვენ წინაა, იკითხეთ, შეიძლება თუ არა მისი როგორმე გაუმჯობესება, გადაწყვიტეთ ერთი რამ, რისი გაკეთებაც ახლავე შეგიძლიათ, და გააკეთეთ ის; შემდეგ გაიმეორეთ. თეორიისადმი ერთგულება სავალდებულო არ არის — ავტორი მას წმინდა პრაგმატულ მიდგომად წარმოაჩენს, რომლის ღირებულებაც უკეთესი დოკუმენტაციის შექმნაში მდგომარეობს.